Prayer times

Jafari (Shia) calculations for any location on earth — preset methods, several at once, or fully custom angles; a day, a month, or a whole year per request. High-latitude dates are handled with the TwilightAngle rule, and Islamic midnight is the midpoint of sunset to true dawn.

GET https://theshia.org/api/v1/prayer-times

Parameters

lat required* latitude, -90 to 90 (decimal degrees, rounded to 2 dp for caching). *Not needed when city is given.
lng required* longitude, -180 to 180 (2 dp). *Not needed when city is given.
city optional city id from /cities (e.g. london, tehran, karbala) — sets lat, lng and tz automatically and overrides them.
method default: Tehran preset id (full value table under Calculation methods) · comma list "Tehran,Jafari" · "all" (all 16) · "custom" (with the angle parameters below).
fajrAngle custom only Fajr sun-depression angle, 4 to 24 degrees. Required when method=custom.
ishaAngle custom only Isha angle, 4 to 24 degrees. Give this OR ishaInterval.
ishaInterval custom only Isha as minutes after maghrib, 0 to 180. Alternative to ishaAngle.
maghribAngle custom only Maghrib sun-depression angle, 0.5 to 12 degrees (Shia methods typically 4–4.5).
maghribInterval custom only Maghrib as minutes after sunset, 0 to 120. Alternative to maghribAngle.
date optional a single day, YYYY-MM-DD.
month default: current 1 to 12, combined with year. Ignored when date is given.
year default: current 1900 to 2100. Given ALONE (no month/date) = the full year, single method only.
tz optional IANA timezone (e.g. Europe/London) — adds local HH:mm strings next to the UTC instants. Auto-filled from city.

Budget: days × methods per request must be ≤ 496 (a month allows all 16 methods; a year allows one).
Response: meta { lat, lng, city?, tz, qibla, method? } and per day: date + imsak, fajr, sunrise, dhuhr, asr, sunset, maghrib, isha, midnight as ISO 8601 UTC instants (+ local { … } when tz is set). Multiple methods return results: [ { method, days } ].
Always applied: TwilightAngle high-latitude rule; imsak = fajr − 10 min; midnight = midpoint of maghrib and the next day's fajr.

Open live example ↗

Code samples

curl

curl "https://theshia.org/api/v1/prayer-times?city=london&method=Tehran&year=2026&month=7"

JavaScript

const res = await fetch("https://theshia.org/api/v1/prayer-times?city=london&method=Tehran&year=2026&month=7");
const data = await res.json();

Python

import requests

data = requests.get("https://theshia.org/api/v1/prayer-times?city=london&method=Tehran&year=2026&month=7").json()

Rate limits & fair use

Responses are cached hard at the edge — please cache on your side too. Uncached requests are limited to 100 per minute per IP; oversized requests (over 496 day×method computations) are rejected. Free for community use, no uptime guarantee.