# Adhan Prayer Times API

> Public, read-only JSON API for calculated Islamic prayer times, location lookup, yearly/monthly calendars, Hijri metadata, Qibla bearing, timezone detection, next prayer, and Islamic night divisions.

- Base URL: `https://adhan2.gitstats.icu`
- Human documentation: `https://adhan2.gitstats.icu/docs`
- API version: `1.0.0`
- Authentication: none
- Response format: JSON

## Endpoints

- `GET /health` — service status and version.
- `GET /api/v1/methods` — supported calculation methods, madhabs, and high-latitude rules.
- `GET /api/v1/geocode?q={place}` — resolve a place to one coordinate pair. The normalized query must contain 2–200 characters. Optional `lang=en|de` returns names in that language.
- `GET /api/v1/times?latitude={lat}&longitude={lon}` — calculate one day from coordinates.
- `GET /api/v1/times/by-city?city={city}&country={country}` — geocode a city and calculate one day. `country` is optional; the combined normalized query must contain 2–200 characters.
- `GET /api/v1/calendar/{year}?latitude={lat}&longitude={lon}` — calculate every day in a year (including leap years). Supported years: 1900–2100.
- `GET /api/v1/calendar/{year}/{month}?latitude={lat}&longitude={lon}` — calculate all days in a month. Supported years: 1900–2100.

## Daily and calendar parameters

`latitude` (−90..90) and `longitude` (−180..180) are required except on `/times/by-city`. Optional parameters:

- `date`: exactly `YYYY-MM-DD`; defaults to the current date in the detected/requested local timezone. Unrepresentable calculation dates return `400`.
- `timezone`: IANA timezone such as `Europe/Berlin`; detected from coordinates when omitted.
- `method`: defaults to `muslim_world_league`. Use `/api/v1/methods` for all current IDs.
- `madhab`: `shafi` (default), `hanafi`, `maliki`, or `hanbali`. Maliki and Hanbali use the one-shadow Asr calculation provided by the engine for Shafi.
- `high_latitude_rule`: `twilight_angle` (default), `middle_of_night`, or `seventh_of_night`.
- `fajr_angle`, `isha_angle`: optional custom angles in degrees from 0.1 to 30.0. A custom Isha angle overrides an interval-based method's Isha interval.
- `adjust_fajr`, `adjust_sunrise`, `adjust_dhuhr`, `adjust_asr`, `adjust_maghrib`, `adjust_isha`: whole-minute offsets from −120 to 120; default 0.

## Examples

```http
GET /api/v1/times?latitude=52.52&longitude=13.405&date=2026-07-10&method=muslim_world_league&madhab=shafi
GET /api/v1/times/by-city?city=Berlin&country=Germany
GET /api/v1/calendar/2026/7?latitude=52.52&longitude=13.405
```

## Success schema

Successful requests wrap results in `data`. Daily data contains:

- `date`, `hijri`, `timezone`, and `utc_offset`.
- `method: {id, name}`, `madhab`, and `high_latitude_rule`.
- `coordinates: {latitude, longitude}`.
- `qibla: {degrees_from_true_north}`.
- `times`: `fajr`, `sunrise`, `dhuhr`, `asr`, `maghrib`, `isha`; each has `local` (`HH:MM`) and `iso` (ISO 8601 with offset).
- `night`: `first_third_end`, `midnight`, `last_third_start`; each has `local` and `iso`. Fractions use elapsed time from adjusted Maghrib to the following sunrise, including daylight-saving transitions.
- `next_prayer: {name, local, iso, seconds_until}`. Returns the next chronological milestone across the requested and following day, including sunrise and accounting for adjusted event order. Countdown uses elapsed time. If both days are entirely in the past, the historical next-day Fajr fallback has `seconds_until: 0`.

City responses additionally contain `location`. Calendar responses contain a `data` array and `meta: {year, days}` for yearly calendars or `meta: {year, month, days}` for monthly calendars. Every daily item includes the same Hijri metadata.

Hijri values use an arithmetic Islamic civil calendar and can differ from locally announced moon-sighting dates.

## Errors

Errors use an appropriate HTTP status and this JSON shape:

```json
{"error":{"code":"invalid_request","message":"Human-readable explanation."}}
```

Calendar responses are gzip-capable and cacheable for 60 seconds. Each worker permits one active calendar generation; if it is already busy, the API returns `429` with `Retry-After: 2`. Location searches use a bounded wait for the shared rate limit and can return `503` with `upstream_unavailable` when busy or when the geocoding provider is temporarily unavailable. API errors and daily responses use `Cache-Control: no-store`; successful geocoding responses vary by language.

## Important calculation guidance

Results are astronomical estimates. They may differ from local mosque timetables because of calculation authority, local adjustments, rounding, elevation, or policy. Choose the method used by the relevant regional authority and disclose this limitation to end users. Do not present API output as an authoritative religious ruling.