One deterministic service for Islamic timekeeping: prayer times, Qibla, Hijri dates, and crescent data. Every route is a plain GET that returns flat JSON. This page is a usage reference — how to call it and what comes back.
All endpoints live under /v1 on your issued host. Every call carries your key in an X-API-Key header, sent server-side — never embed a key in client-side code. Keys are issued on onboarding: write to prayer@kairoico.com for an evaluation key.
Every reply is a flat JSON object: ok (boolean), fields (the named result values), and raw (the same values as a single line, handy for logs). Times are HH:MM:SS in the location's own civil clock, with the timezone reported for audit.
The daily prayer times for a date and place. Returns imsak, fajr, sunrise, dhuhr, asr, maghrib, isha, midnight and the night thirds, plus the angles used, the Hijri date, and the Qibla bearing — all in one call.
| Parameter | Req | Description |
|---|---|---|
| year, month, day | yes | Gregorian date. |
| lat, lon | yes | Decimal degrees, north/east positive. |
| method | no | Calculation convention (default MWL). See the methods table. |
| asr | no | 1 = Shāfiʿī (default), 2 = Hanafī. |
| shafaq | no | general | ahmer | abyad (Moonsighting method). |
| midnight | no | sunni | shia. |
| highlat | no | High-latitude convention. See the high-latitude table. |
| imsak | no | Minutes before fajr for imsak (default 10). |
| elev | no | Observer elevation in metres (horizon-dip correction). |
| tz | no | Seconds east of UTC to force an offset; default resolves the location's zone. |
| fajr_angle, isha_angle, maghrib_angle, isha_interval | no | Override the convention's angles/interval with custom values. |
| round | no | up | down | nearest | none for the civil times. |
| parity | no | 1 serves the published authority calendar verbatim on the civil times when one is on file for that method and year; the astronomical times always remain under exact. The reply is tagged "parity": "<authority>_<year>", or "parity": "unavailable" when no table is on file. Omitted when off. |
A full month (or any day-span) of prayer times for a place in one call — the same per-day maths as the daily route, DST-aware. Accepts every option the daily route does.
| Parameter | Req | Description |
|---|---|---|
| year, month | yes | Month to render. |
| day, n_days | no | Optional start day and length; defaults to the whole month. |
| lat, lon | yes | Decimal degrees. |
| method, asr, highlat, … | no | Same options as /v1/sun/prayer. |
Initial great-circle bearing and distance to the Kaaba from any location. Also rides along inside every prayer reply.
| Parameter | Req | Description |
|---|---|---|
| lat, lon | yes | Decimal degrees. |
Convert a Gregorian date to the Hijri calendar date, with the anchoring new-moon exposed.
| Parameter | Req | Description |
|---|---|---|
| year, month, day | yes | Gregorian date. |
Moon phase, elongation, and illumination for any moment — the raw ingredients behind sighting the crescent that starts Ramadan and Eid.
| Parameter | Req | Description |
|---|---|---|
| year, month, day | yes | Gregorian date. |
| hour | no | Hour of day (UTC), default 0. |
The point on Earth the sun is directly over. On the two days a year it stands over the Kaaba, anyone can find Qibla by their own shadow — no compass needed.
| Parameter | Req | Description |
|---|---|---|
| year, month, day | yes | Gregorian date. |
| hour | no | Hour of day (UTC), default 0. |
method=)| Token | Convention |
|---|---|
| MWL | Muslim World League |
| ISNA | Islamic Society of North America |
| Egypt | Egyptian General Authority of Survey |
| Karachi | University of Islamic Sciences, Karachi |
| UmmAlQura / Makkah | Umm al-Qura University, Makkah |
| Dubai | Dubai (UAE) |
| Qatar | Qatar |
| Gulf | Gulf Region |
| Kuwait | Kuwait |
| Singapore | Majlis Ugama Islam Singapura |
| France | Union des Organisations Islamiques de France |
| Turkey | Diyanet İşleri Başkanlığı |
| Russia | Spiritual Administration of Muslims of Russia |
| Tehran | Institute of Geophysics, University of Tehran |
| Jafari | Shia Ithna Ashari (Jafari) |
| MoonsightingCommittee | Moonsighting Committee Worldwide (seasonal) |
highlat=)| Token | Behaviour when fajr/isha does not occur |
|---|---|
| none | Return “does not occur” (default — honest). |
| middle | Middle of the night. |
| seventh | One-seventh of the night. |
| angle | Angle-based proportion of the night. |
| nearest_day | Carry the clock time from the nearest day the prayer does occur. |
| nearest_lat | Use the nearest latitude at which the prayer occurs. |
| Parameter | Values |
|---|---|
| asr | 1 Shāfiʿī · 2 Hanafī |
| shafaq | general · ahmer · abyad |
| midnight | sunni · shia |
| round | up · down · nearest · none |
Every plan carries a published ceiling. There are no hidden per-IP throttles and no silent degradation: you either get a 200 with a real computed answer, or a 429 that tells you the ceiling was reached. Nothing in between.
Each plan has three independent limits:
| Limit | What it means |
|---|---|
| sustained | Requests per second you can hold indefinitely. Unused capacity accrues up to the burst ceiling. |
| burst | The most requests that can be served in one instantaneous spike after an idle period — the adhan-moment allowance. |
| concurrent | How many of your requests may be in flight at the same instant. Your private slice, so no other customer's traffic can crowd you out — and yours cannot crowd out theirs. |
| Plan | Sustained | Burst | Concurrent |
|---|---|---|---|
| Evaluation | 1 / s | 10 | 1 |
| Starter | 5 / s | 10 | 4 |
| Growth | 25 / s | 50 | 8 |
| Scale | 75 / s | 150 | 16 |
These ceilings apply to every route on this page; prayer times, Qibla, Hijri and crescent calls all draw on the same allowance, and none of them carries an extra per-route cap. A month call is one request against your limit, not thirty — fetching a whole month or a whole year through /v1/sun/prayer/month is the cheapest way to stay inside a plan.
On what these numbers are not: they are a fairness and billing pace. If your ceiling is the thing constraining you, that is a plan question and we can raise it.
Need a higher ceiling, a dedicated instance, or terms for an appliance or OEM programme? prayer@kairoico.com.
Errors return a JSON object with a numeric code and a human error string. Common cases:
| Code | Meaning |
|---|---|
| 400 | Missing or malformed parameter. |
| 401 | Invalid or missing API key on a keyed request. |
| 429 | Rate ceiling reached for your plan — see Rate limits. |
Need a higher tier, a dedicated instance, or appliance and OEM terms? prayer@kairoico.com.