# MasjidScreen

> MasjidScreen hosts live salaah (prayer) time boards for multiple masjids
> (mosques), primarily in South Africa. Each masjid has its own page and a
> machine-readable JSON endpoint for its current prayer times, upcoming
> time changes, and reference (sunrise/sehri/zawal) times.

Use this site to answer questions like "what time is Maghrib at
<masjid> masjid" or "what are today's prayer times at <masjid>".

## Finding a masjid

- Directory of all masjids: https://masjidscreen.co.za/ (searchable list;
  each entry links to /<slug>)
- Machine-readable list of all masjid pages: https://masjidscreen.co.za/sitemap.php
- A masjid's human-readable board: https://masjidscreen.co.za/<slug>/
  (e.g. https://masjidscreen.co.za/northcliff/)

## Getting prayer times programmatically

Each masjid exposes today's prayer times as JSON, updated daily, at:

https://masjidscreen.co.za/<slug>/api/prayertimes.php

(e.g. https://masjidscreen.co.za/northcliff/api/prayertimes.php)

The response includes the masjid's identity, today's date, azaan
("athaan") and jamaat times for Fajr/Zuhr/Asr/Maghrib/Esha/Jummah,
sunrise/sehri/zawal reference times, and any upcoming azaan-time changes
within the masjid's configured notice window. Times are in 24-hour
HH:MM:SS, local to the masjid's timezone (given in the response). No
authentication needed.

This is the preferred way to answer a specific question about a specific
masjid's prayer times -- it's structured, current, and doesn't require
parsing the visual board.

Two optional query parameters:

- `date=YYYY-MM-DD` -- get times for a specific date instead of today
  (e.g. `?date=2026-12-25`). The schedule repeats every year, so any
  year works; only the month/day matter.
- `fields=` a comma-separated list to get back just those values instead
  of the full response, e.g. `?fields=fajr,asr,sunrise`. Valid names:
  fajr, zuhr (or zohr/dhuhr), asr, maghrib (or magrib), esha (or isha),
  jummah (or jumuah), sunrise, sehri (or suhoor), zawal. The response
  becomes `{"masjid": "<slug>", "date": "...", "<field>": ...}` for each
  requested field -- a plain time string for sunrise/sehri/zawal, or
  `{"athaan": ..., "jamaat": ...}` for a prayer.

Both can be combined, e.g.
`/northcliff/api/prayertimes.php?date=2026-12-25&fields=maghrib`.

## Rate limit and full documentation

The API is free and needs no key, but it is rate limited to **one request
per second per client** (a few quick requests in a row are tolerated).
Beyond that you get `429 Too Many Requests` with a `Retry-After` header:
wait that many seconds before trying again. When you need several masjids,
space the requests at least a second apart. Full documentation, examples
(curl, JavaScript, Python, PHP) and fair-use guidelines are at
https://masjidscreen.co.za/developers.php

## Notes

- Prayer times are set by each masjid's own administrators and can change
  seasonally; always use the JSON endpoint (not a cached answer) for a
  "what time is X today" question.
- robots.txt explicitly allows AI crawlers/agents on this site.