mptwaktusolat / api-waktusolat

Serve the accurate Malaysia Prayer Time data

Waktu Solat API | Malaysia Prayer Time API

Formally 'MPT Server'

A Malaysia Prayer Time REST API server, originally build for Malaysia Prayer Time app. Provide necessary data and procssing for the app features to work.

Getting Started

Prepare environment

Note

If you didn't plan to use /api/jadual_solat endpoint, you may skip this step and proceed to Start development server

Create .env.local at the root the project. Example environment vars are in the .env.example file. Or run:

cp .env.example .env.local

/api/jadual_solat will generate PDF based on the prayer data. To do so, it need to access Chrome. In development, you can use your local Chrome, but on Production, you need to setup the Chrome instance somewhere. I use https://www.browserless.io/ service.

Grab the API key and paste to BROWSERLESS_TOKEN key.

Start development server

First, install the dependencies:

yarn install

Run the development server:

yarn dev

Open http://localhost:3000 with your browser to see the result.

The pages/api directory is mapped to /api/*. Files in this directory are treated as API routes instead of React pages.

(Optional) Make your own Firestore database instance

/api/v2/solat endpoint will fetch the prayer data from Firestore datatabase. To prepare the data needed, see https://github.com/mptwaktusolat/waktusolat-fetcher.

Once setup, set FIREBASE_API_KEY to your own Firebase API key.

How are the prayer time data is updated every month? (Old method)

Note

This method is used to update the /solat endpoint. Now that the endpoint is deprecated, I'll stop the automatic workflow soon. For latest method on fetching the prayer time, see waktusolat-fetcher

The data is updated automatically every month using GitHub Action. The overall flow is depicted in the diagram below.

flowchart TD
    A{{JAKIM}}
    A <--> C
    C[[Fetch latest prayer data]] --- D[(db.json)] & E[(log.json)] --> F(Commit & push)
    F -->|Vercel build triggered| G[Deployed to Vercel]

View the fetcher implementation here.

Deployment status

API endpoints

Public usage

See https://api.waktusolat.app/docs

Internal usage (MPT App)

• POST /api/feedback

api-waktusolat's Issues

Add NGS03

mptwaktusolat/app_waktu_solat_malaysia#164

And update the /locations data

[API V2] Cannot retrieve default June

When using this:
https://mpt-server.vercel.app/api/v2/solat/sgr01?year=2023

{
    "error": "No data found for zone: SGR01 for JUNE/2023"
}

But, it can fetch when supplying the &month
https://mpt-server.vercel.app/api/v2/solat/sgr01?year=2023&month=6

{
    "zone": "SGR01",
    "year": 2023,
    "month": "JUN",
    "last_updated": "2023-05-18T16:57:05.436Z",
    "prayers": [
        {
            "hijri": "1444-11-12",
            "maghrib": 1685618520,
            "day": 1,
            "asr": 1685608740,
            "syuruk": 1685574060,
            "isha": 1685623020,
            "dhuhr": 1685596440,
            "fajr": 1685569740
        },
        {
            "fajr": 1685656140,
            "syuruk": 1685660460,
            "maghrib": 1685704980,
            "isha": 1685709480,
            "dhuhr": 1685682840,
            "hijri": "1444-11-13",
            "asr": 1685695140,
            "day": 2
        },
        {
            "maghrib": 1685791380,
            "fajr": 1685742540,
            "dhuhr": 1685769240,
            "day": 3,
            "hijri": "1444-11-14",
            "asr": 1685781540,
            "syuruk": 1685746920,
            "isha": 1685795880
        },
        {
            "isha": 1685882280,
            "day": 4,
            "fajr": 1685828940,
            "maghrib": 1685877780,
            "dhuhr": 1685855640,
            "syuruk": 1685833320,
            "asr": 1685867940,
            "hijri": "1444-11-15"
        },
        {
            "syuruk": 1685919720,
            "hijri": "1444-11-16",
            "maghrib": 1685964180,
            "isha": 1685968680,
            "dhuhr": 1685942040,
            "day": 5,
            "asr": 1685954400,
            "fajr": 1685915400
        },
        {
            "fajr": 1686001800,
            "dhuhr": 1686028500,
            "day": 6,
            "hijri": "1444-11-17",
            "asr": 1686040800,
            "syuruk": 1686006120,
            "maghrib": 1686050580,
            "isha": 1686055140
        },
        {
            "maghrib": 1686137040,
            "asr": 1686127200,
            "syuruk": 1686092520,
            "day": 7,
            "dhuhr": 1686114900,
            "isha": 1686141540,
            "fajr": 1686088200,
            "hijri": "1444-11-18"
        },
        {
            "dhuhr": 1686201300,
            "syuruk": 1686178920,
            "hijri": "1444-11-19",
            "isha": 1686227940,
            "maghrib": 1686223440,
            "asr": 1686213600,
            "fajr": 1686174600,
            "day": 8
        },
        {
            "fajr": 1686261000,
            "isha": 1686314340,
            "dhuhr": 1686287700,
            "day": 9,
            "syuruk": 1686265320,
            "maghrib": 1686309840,
            "asr": 1686300060,
            "hijri": "1444-11-20"
        },
        ...
    ]
}

Add downloadable JSON for location code

https://mpt-server.vercel.app/locations

Error fetching `KTN03`, need to change to `KTN02`

Related to mptwaktusolat/app_waktu_solat_malaysia#160

waktu solat v2

Objective

• Develop new endpoint for /api/solat/.
• Make data fetching from JAKIM occur before the upcoming month

TODO

• Design in intended responses
• Design new data fetching and processing pipeline (waktusolat-fetcher)
• Setup schedule to automate fetching
• Migrate database from using JSON to Firebase
• Add /v2 to mpt-server (keep the original as is, to prevent breaking)

Motivation

Currently the responses that returned from that endpoint is same and identical to what JAKIM API returned. This is fine because the original objective is to use this endpoint as a backup when JAKIM API goes down (Originally introduced in mpt-backup-api).

However, the current implementation has few drawbacks.

Current problems and possible solutions

Delay in data updates

Problem	Solution
The earliest data fetching can only be done in the first day of the month. In addition, the CI workflow is scheduled using Zulu time. So, it will take a few hours before fetching for the month can be done. So, app will be fallback to use JAKIM API when mpt-server data is not ready yet	We can use other 3rd party cron job services to fetch the data at 00:00, but I'm afraid everyone is doing the same at it would cause problem to JAKIM server. Instead, we'll try to retrieve prayer data for upcoming month in advance

Data responses and parser

Problem	Solution
The API currently return a date and time separately, in text (See it yourself). A parser needs to be designed to properly parsed the data (See current implementation in mpt app). In addition, sometimes, an expected changes with JAKIM API (for example: mptwaktusolat/app_waktu_solat_malaysia#103 (comment)) require a new app update.	Parse date and time to UNIX epoch, so it will be up the client to parse easily to whatever they want. Also, if unexpected changes occur to the JAKIM API, a fix can be issued immediately without publishing a new app update

Storing data

Problem	Solution
Currently. the fetched data stored in JSON database. It doesn't cause any issue, it just for every data update, a new site deployment is made. This approach has one benefit because the data and the server are in one server (not separated by physical distance)	Store the fetched data in database (I'm thinking of mongodb/Firebase). Additionally, we can add versions so the endpoint will be able to retrieve the previous month, current month, and upcoming month. There might be some latency issue. However, that can be overcome by properly setup caching etc. We need to make sure that server and database are physically close to each other

Risks

Keep this risk in mind. Since we are using JAKIM API, which is undocumented, and I don't think it is for public use. The API can break anytime and can mess up our API database.

Move internal API implementation to waktusolat.app

Move several API that were solely used in MPT app to https://waktusolat.app/api/. Leave Waktu Solat API clean for public usages.

For example: Mosque endpoint. This is only for decorative purposes for MPT app

Deployment workflow not triggered after fetch workflow

Idk. Maybe the commit author is a bot???

• Trigger deployment workflow after fetch workflow
• Add workflow_dispatch to enable manual deployment trigger

Migrate to Next 13

https://nextjs.org/blog/next-13