Guides

Recommended pull chain:

1. Discover methods: call GET /v1/methods and cache by id. This includes registry methods and harvested authority dataset IDs.
2. Resolve location recommendation: call GET /v1/methods/recommended?lat=...&lng=.... Keep recommendedMethod, fallbackLevel, and selectionPath.
3. Get prayer times: call POST /v1/prayertimes with normalizeCoordinates, and optional methodOverride if user-selected.
4. Expand details on demand: call GET /v1/methods/:methodId for full parameters to display in client UI.

curl "http://localhost:8080/v1/methods" -H "X-API-Key: YOUR_KEY"
curl "http://localhost:8080/v1/methods/recommended?lat=3.1579&lng=101.7123&normalizeCoordinates=true" -H "X-API-Key: YOUR_KEY"
curl "http://localhost:8080/v1/methods/recommended?lat=3.1579&lng=101.7123&normalizeCoordinates=true" -H "X-API-Key: YOUR_KEY"
curl -X POST "http://localhost:8080/v1/prayertimes" -H "Content-Type: application/json" -H "X-API-Key: YOUR_KEY" -d '{"lat":3.1579,"lng":101.7123,"date":"2026-02-21","prefer":"allow_fallback","normalizeCoordinates":true,"hijriOffset":1}'
curl "http://localhost:8080/v1/methods/jakim" -H "X-API-Key: YOUR_KEY"

The API utilizes a three-tier Master Compliance Registry to resolve the data source for every request:

• Tier 1 (Harvested Official): Verified government timetables. Used for MYS (JAKIM), SAU (Umm al-Qura), ARE (IACAD), SGP (MUIS). No buffers applied.
• Tier 2 (Computed Official): Government-verified parameters (High-Precision). Used for IDN, PHL, EGY. Includes +1m to +2m safety buffers for Maghrib/Fajr.
• Tier 3 (Global Physics): Standard astronomical calculations with precautionary safety offsets.

Always inspect the provenance object in the response to see the specific logic, buffers, and authority used.

Clients can manually adjust the resolved Hijri date using the hijriOffset parameter in POST /v1/prayertimes:

• "hijriOffset": 1: Advance the Hijri date by 1 day.
• "hijriOffset": -1: Delay the Hijri date by 1 day.

Ramadan Intelligence: When a request falls within the Hijri month of Ramadan (Month 9), the compliance layer automatically applies religious overrides, such as the 120-minute Isha shift used in Saudi Arabia.

To ensure your Muslim Companion app is reliable, the client-side code must handle the bridge between Harvested and Calculated data.

1. The "Iftar Safety" Logic (Maghrib)

In the Middle East and SE Asia, atmospheric refraction makes the sun "visible" for ~120 seconds after it sets.Logic: If mode is NOT harvested_official, the app should (at your discretion) add +2 minutes to the Maghrib time before display.Note: Tier 2 and Tier 3 responses already include precautionary buffers in the times object.

2. The "Suhur Safety" Logic (Fajr)

3. The "Madhab" Enforcement (Asr)

Generic APIs default to 1:1 shadow (Shafi'i). For 1.5 billion Muslims in Pakistan, India, Turkey, and Afghanistan, this is incorrect.Logic: WaktuSolat automatically identifies the iso3 code and switches the asrRule to Hanafi based on the Master Registry.

4. High Latitude Fasting

Above 48° (e.g., London, Oslo), night never fully disappears in summer.Logic: Inspect provenance.high_latitude_applied. Our API enforces the "One Seventh of the Night" rule automatically. Do not apply manual offsets on top of this.

5. Hijri "Moon Sighting" Adjustments

Always allow users to set a manual offset (±1 or ±2 days).Implementation: Pass this as hijriOffset in your body. This ensures Ramadan triggers (like the 120m Saudi Isha shift) sync with local sightings.

WaktuSolat employs a dual-engine architecture to guarantee global uptime without sacrificing absolute local accuracy:

• Harvested Official (Primary): When mode: "harvested_official", the API returns the exact, pre-calculated timetable legally published by the local Islamic Ministry (e.g., JAKIM, MUIS, Umm al-Qura).
• Mathematical Engine (Fallback): If official data is unavailable (e.g., deep ocean, polar regions, high altitude), the API seamlessly falls back to mode: "calculated_fallback". Unlike generic astronomical libraries, this engine natively applies the same +2/-2 minute jurisprudential safety margins used by Islamic Ministries.

Required Client App Logic

1. UI Badge: You should display an "Official Mosque Data" badge when resultIsOfficial === true, letting users know the times are verified by their local authority.
2. Night Calculations: The API calculates complex night divisions regardless of the mode.
   • midnight: The mid-point between Maghrib and the next day's Fajr (used for the permissible window of Isha).
   • last_third: The final third of the night (Qiyam), highly sought after for Tahajjud prayers. Make sure your app's push notifications trigger specifically on the last_third timestamp.
3. Offline Caching: Since our Mathematical Engine mirrors the official offsets, you can confidently cache the 365-day calculated array on your client app for off-grid usage.

Fallback order:

1. harvested_official_authority
2. official_country_calculation_parameters
3. country_calculation_profile
4. regional_profile
5. global_default_profile

Always render these response fields in your client:

• mode, resultIsOfficial, fallbackLevel, fallbackReason
• methodAuthority, methodOriginCountry, methodOriginRegion
• recommendedMethod, methodUsed, selectionPath[]
• juristic_settings (Applied rule, basis, and source)
• tzIdUsed, timezoneSource, resolutionMethod

If warnings contains USER_OVERRIDE_USED, keep resultIsOfficial=false unless override exactly matches verified official method.

The API implements a Juristic Enforcement Layer that maps every country to its theological norm:

• Hanafi (Shadow 2:1): Enforced for Pakistan, India, Bangladesh, Turkey, and Central Asia.
• Shafi'i (Shadow 1:1): The global standard for Malaysia, Indonesia, Middle East, and the West.

Control this behavior via the madhab parameter (shafi | hanafi). Always inspect juristic_settings to confirm the applied rule.

• Map sidebar has an API Key field at the top under Test Location.
• Map always displays Recommended Method and Method Used with full params.
• Override selector supports method ID and custom-angle mode with immediate recompute.
• Zone cards display zoneSource, uniformity flag, high-latitude audit fields, and selection path.

Validate interactively in Coverage Map and Console.

cd /Users/sallahuddin/Desktop/waktusolat
npm run start:api
npm run build:docs
npm run start:docs

Docs proxy uses API_URL (default http://localhost:8080). If API is down, /swagger and proxied /v1/* calls will fail.