Quick start
Request the first 20 mosques with retained timetables. Public read endpoints do not require an API key.
curl "https://sirat.uk/mosques/v1/mosques?limit=20"Browser applications can call the API from any origin:
const response = await fetch("https://sirat.uk/mosques/v1/mosques?limit=20");
if (!response.ok) throw new Error(`Directory request failed: ${response.status}`);
const mosques = await response.json();Endpoints
GET /v1/mosques
List eligible mosques. Each result contains its routing id, mosque name, address, website_url, lat, lng, and coordinate_precision.
Every returned mosque has a retained timetable and an independently acquired coordinate with no active hold. Location filters use that same authoritative coordinate.
Public identifiers use the opaque mosque-000001 format. They are assigned from this directory's own timetable cohort and do not encode or reproduce an upstream directory identifier.
GET /v1/mosques/{id}
Return one eligible mosque's name, address, website, coordinate, and precision tier.
GET /v1/mosques/{id}/times
Return grouped prayer times for one ISO date, or for an inclusive range when both from and to are supplied. Without date parameters, the endpoint uses today’s UK date.
GET /v1/times
Query flat prayer-time records by required ISO date, with an optional prayer value and location filters. Each result includes the mosque coordinate and coordinate_precision.
GET /v1/snapshot
Retrieve all eligible mosques and times for the next 45 calendar days, including today, in one JSON response.
GET /v1/health
Check service health, live-source counts, stale-source counts, and the latest refresh state.
Pagination
/v1/mosques uses positive limit and non-negative offset values. The default limit is 200 and the maximum is 1,000.
https://sirat.uk/mosques/v1/mosques?limit=100&offset=200Continue increasing offset until the response contains fewer records than your requested limit.
Errors and request limits
Errors use a JSON detail field. Handle these status codes:
- 404
- The requested mosque does not exist.
- 422
- A query parameter is missing or invalid.
- 429
- The request limit was reached. Wait for the
Retry-Afterduration. - 5xx
- The service could not complete the request. Retry with backoff.
The origin allows 120 public API requests per client each minute. Successful responses include RateLimit-Limit. A 429 response is not cacheable and also includes RateLimit-Remaining, RateLimit-Reset, and Retry-After.
Freshness and caching
Timetables are refreshed regularly from public mosque sources, but retained records may be stale or awaiting review. Absence of a day in the response means no retained time is available for that day.
The snapshot response includes generated_at and an ETag. Send that value in If-None-Match; an unchanged snapshot returns 304 Not Modified. Public clients and shared caches may retain snapshots for five minutes and other successful reads for one minute, as directed by Cache-Control.
Health and error responses use Cache-Control: no-store. Use /v1/health to check whether the published dataset is healthy before a bulk import.
Versioning
The current API version is v1. Additive fields may appear within a version. Planned breaking API contract changes will use a new version prefix; urgent security, legal, or protective changes may be applied without advance notice.
Use the API responsibly
Cache responses where practical, honour Cache-Control, use conditional snapshot requests, and avoid repeated requests that provide no user benefit.
- The published JSON dataset is available under ODC-By 1.0; follow the data and attribution guidance.
- The acceptable-use terms govern access to the hosted website and API; ODC-By governs reuse of the published dataset.
- Prayer times can change. Where practical, help users check the mosque's official information and report a correction.
For complete machine-readable schemas and interactive examples, use the OpenAPI reference.