Muslim.Blue for developers

API documentation

Everything the free Muslim.Blue API answers, with an example of each. It is read-only JSON over HTTPS, and every route is a GET.

The basics

The address

Every route below starts with this address:

The API's address

https://muslim.blue/wp-json/blue/v1/public

Keys

Most routes work without a key. The calculator needs one. Send your key in the X-Api-Key header; never put it in the address. Get a free key on your keys page.

A request with a key

curl -H "X-Api-Key: YOUR_KEY" "https://muslim.blue/wp-json/blue/v1/public/hijri"

Limits

A key allows 60 requests a minute and 10,000 a day (UTC). Without a key, one network address may make 60 requests a minute and 2,500 a day that reach us; answers from our cache never count.

Answers to a key carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds) for the minute, and X-RateLimit-Day-Limit and X-RateLimit-Day-Remaining for the day. Past a limit you get 429 with Retry-After, the seconds to wait.

Caching and ETags

Every answer has an ETag. Keep it, send it back in If-None-Match, and when nothing changed you get 304 with no body. A 304 never counts toward your day, so asking often is cheap.

A masjid's times are cached for 60 seconds and cleared the moment the masjid changes them. The calculator and the Hijri date are cached for an hour, and the methods for a day.

Asking again with the ETag

curl -i -H 'If-None-Match: W/"5d1f0c9e8b7a6f5e4d3c2b1a09f8e7d6"' "https://muslim.blue/wp-json/blue/v1/public/masjids/example-masjid/year"

Times

Times are local, in 24-hour HH:MM, in the masjid's own time zone (tz). A prayer is never shown before it begins: its minute is rounded up, while sunrise and midnight are rounded down. The calculator also gives each exact moment in ISO 8601.

Published or calculated

A masjid that publishes on Muslim.Blue answers its own iqamah, Jumu'ah, Eid and taraweeh times. Every other US masjid is listed from public records with calculated adhan times: its days have "iqamah": null and the note "iqamah not published by this masjid", and the day and month routes say "times": "calculated". Please show that word wherever you show such times.

Some listed masjids could be placed only at the middle of their ZIP code area. Their day and month answers say "approximate": true, and their calculated times may be off by a few minutes.

The moment a masjid publishes, the same addresses answer its own times.

The whole API in one file

The OpenAPI 3.1 document describes every route and answer, for code generators and API tools.

Masjids

GET `/masjids`

Find masjids by name, place or distance no key needed

Words are matched against each masjid's name, city, state and ZIP code, in any order. A point (lat and lng) orders the results nearest first, with the distance in kilometers; a point alone finds the nearest masjids within 250 km. The point is rounded to two decimals (about a kilometer) before it is used.

Parameters of /masjids
Name	Where	What it is
`q`	optional	Words to look for: a name, a city, a state or a ZIP code. At least two letters unless you give a point. string
`lat`	optional	Latitude of the point to search near. Give it with lng. number
`lng`	optional	Longitude of the point to search near. Give it with lat. number
`limit`	optional	How many masjids to answer, 1 to 50. integer

Example request to /masjids

curl "https://muslim.blue/wp-json/blue/v1/public/masjids?q=columbia%20sc"

Example answer from /masjids

{
  "q": "columbia sc",
  "near": null,
  "masjids": [
    {
      "slug": "example-masjid",
      "name": "Example Masjid",
      "kind": "masjid",
      "city": "Columbia",
      "region": "SC",
      "country": "US",
      "listed": false,
      "km": null,
      "brand": {
        "color": "#1b4f9c",
        "logo": null,
        "photo": null
      }
    },
    {
      "slug": "example-listed-masjid",
      "name": "Example Listed Masjid",
      "kind": "masjid",
      "city": "Columbia",
      "region": "SC",
      "country": "US",
      "listed": true,
      "km": null,
      "brand": {
        "color": null,
        "logo": null,
        "photo": null
      }
    }
  ]
}

GET `/masjids/{slug}`

One masjid no key needed

The masjid's listing: its name, address, map point, time zone and whether it publishes its own times, its color and logo, and for a masjid that publishes on Muslim.Blue, its contact details, livestream, events, halls to book and pages.

Parameters of /masjids/{slug}
Name	Where	What it is
`slug`	in the path	The masjid's address on Muslim.Blue, as in muslim.blue/{slug}. string

Example request to /masjids/{slug}

curl "https://muslim.blue/wp-json/blue/v1/public/masjids/example-masjid"

Example answer from /masjids/{slug}

{
  "slug": "example-masjid",
  "name": "Example Masjid",
  "kind": "masjid",
  "listed": false,
  "tz": "America/New_York",
  "address": {
    "street": "100 Example Street",
    "city": "Columbia",
    "region": "SC",
    "postal": "29201",
    "country": "US"
  },
  "location": {
    "lat": 34.0007,
    "lng": -81.0348
  },
  "brand": {
    "color": "#1b4f9c",
    "logo": null,
    "photo": null
  },
  "contact": {
    "phone": "",
    "website": "https://example.org/",
    "email": ""
  },
  "livestream": [],
  "events": [],
  "spaces": [],
  "pages": {
    "give": "https://muslim.blue/example-masjid/give/"
  }
}

Masjid times

GET `/masjids/{slug}/today`

A masjid's times today no key needed

The composed day for the masjid's own calendar date: adhan and iqamah times, Jumu'ah, Eid and taraweeh, and the Hijri date. A masjid that has not published its own times answers calculated adhan times with "iqamah": null and a note.

Parameters of /masjids/{slug}/today
Name	Where	What it is
`slug`	in the path	The masjid's address on Muslim.Blue, as in muslim.blue/{slug}. string

Example request to /masjids/{slug}/today

curl "https://muslim.blue/wp-json/blue/v1/public/masjids/example-masjid/today"

Example answer from /masjids/{slug}/today

{
  "date": "2026-11-06",
  "weekday": "Friday",
  "tz": "America/New_York",
  "hijri": {
    "day": 26,
    "month": 5,
    "year": 1448,
    "name": {
      "en": "Jumada al-Ula",
      "es": "Yumada al-Ula",
      "ar": "جمادى الأولى"
    },
    "method": "fcna"
  },
  "adhan": {
    "fajr": "05:38",
    "sunrise": "06:48",
    "dhuhr": "12:08",
    "asr": "15:05",
    "maghrib": "17:27",
    "isha": "18:38"
  },
  "iqamah": {
    "fajr": "06:15",
    "dhuhr": "13:15",
    "asr": "15:45",
    "maghrib": "17:32",
    "isha": "19:45",
    "source": {
      "fajr": "rule",
      "dhuhr": "rule",
      "asr": "rule",
      "maghrib": "rule",
      "isha": "rule"
    }
  },
  "jumuah": [
    {
      "slot": 1,
      "khutbah": "13:15",
      "iqamah": "13:45",
      "arrive": null,
      "language": "English",
      "place": "Main hall"
    }
  ],
  "eid": [],
  "taraweeh": null,
  "warnings": [],
  "built_at": "2026-11-06T04:00:00Z"
}

GET `/masjids/{slug}/day/{date}`

A masjid's times on one date no key needed

The composed day for one date, wrapped with the masjid and with "times": "published" or "calculated", so a listed masjid's calculated times are never mistaken for its own.

Parameters of /masjids/{slug}/day/{date}
Name	Where	What it is
`slug`	in the path	The masjid's address on Muslim.Blue, as in muslim.blue/{slug}. string
`date`	in the path	The date, YYYY-MM-DD, from 2000 to 2100. string

Example request to /masjids/{slug}/day/{date}

curl "https://muslim.blue/wp-json/blue/v1/public/masjids/example-masjid/day/2026-11-06"

Example answer from /masjids/{slug}/day/{date}

{
  "masjid": {
    "slug": "example-masjid",
    "name": "Example Masjid",
    "tz": "America/New_York",
    "listed": false,
    "approximate": false,
    "page": "https://muslim.blue/example-masjid/"
  },
  "times": "published",
  "notice": null,
  "attribution": [],
  "date": "2026-11-06",
  "day": {
    "date": "2026-11-06",
    "weekday": "Friday",
    "tz": "America/New_York",
    "hijri": {
      "day": 26,
      "month": 5,
      "year": 1448,
      "name": {
        "en": "Jumada al-Ula",
        "es": "Yumada al-Ula",
        "ar": "جمادى الأولى"
      },
      "method": "fcna"
    },
    "adhan": {
      "fajr": "05:38",
      "sunrise": "06:48",
      "dhuhr": "12:08",
      "asr": "15:05",
      "maghrib": "17:27",
      "isha": "18:38"
    },
    "iqamah": {
      "fajr": "06:15",
      "dhuhr": "13:15",
      "asr": "15:45",
      "maghrib": "17:32",
      "isha": "19:45",
      "source": {
        "fajr": "rule",
        "dhuhr": "rule",
        "asr": "rule",
        "maghrib": "rule",
        "isha": "rule"
      }
    },
    "jumuah": [
      {
        "slot": 1,
        "khutbah": "13:15",
        "iqamah": "13:45",
        "arrive": null,
        "language": "English",
        "place": "Main hall"
      }
    ],
    "eid": [],
    "taraweeh": null,
    "warnings": [],
    "built_at": "2026-11-06T04:00:00Z"
  }
}

GET `/masjids/{slug}/days`

A masjid's times for a range of dates no key needed

Up to 31 composed days, both ends included.

Parameters of /masjids/{slug}/days
Name	Where	What it is
`slug`	in the path	The masjid's address on Muslim.Blue, as in muslim.blue/{slug}. string
`from`	required	The first date, YYYY-MM-DD. string
`to`	required	The last date, YYYY-MM-DD, at most 30 days after from. string

Example request to /masjids/{slug}/days

curl "https://muslim.blue/wp-json/blue/v1/public/masjids/example-masjid/days?from=2026-11-06&to=2026-11-12"

Example answer from /masjids/{slug}/days

{
  "masjid": {
    "slug": "example-masjid",
    "name": "Example Masjid",
    "tz": "America/New_York",
    "listed": false
  },
  "from": "2026-11-06",
  "to": "2026-11-12",
  "days": [
    {
      "date": "2026-11-06",
      "weekday": "Friday",
      "tz": "America/New_York",
      "hijri": {
        "day": 26,
        "month": 5,
        "year": 1448,
        "name": {
          "en": "Jumada al-Ula",
          "es": "Yumada al-Ula",
          "ar": "جمادى الأولى"
        },
        "method": "fcna"
      },
      "adhan": {
        "fajr": "05:38",
        "sunrise": "06:48",
        "dhuhr": "12:08",
        "asr": "15:05",
        "maghrib": "17:27",
        "isha": "18:38"
      },
      "iqamah": {
        "fajr": "06:15",
        "dhuhr": "13:15",
        "asr": "15:45",
        "maghrib": "17:32",
        "isha": "19:45",
        "source": {
          "fajr": "rule",
          "dhuhr": "rule",
          "asr": "rule",
          "maghrib": "rule",
          "isha": "rule"
        }
      },
      "jumuah": [
        {
          "slot": 1,
          "khutbah": "13:15",
          "iqamah": "13:45",
          "arrive": null,
          "language": "English",
          "place": "Main hall"
        }
      ],
      "eid": [],
      "taraweeh": null,
      "warnings": [],
      "built_at": "2026-11-06T04:00:00Z"
    }
  ]
}

One day shown; the answer has all seven.

GET `/masjids/{slug}/month/{month}`

A masjid's times for a month no key needed

Every day of one calendar month, wrapped with the masjid and with "times": "published" or "calculated".

Parameters of /masjids/{slug}/month/{month}
Name	Where	What it is
`slug`	in the path	The masjid's address on Muslim.Blue, as in muslim.blue/{slug}. string
`month`	in the path	The month, YYYY-MM. string

Example request to /masjids/{slug}/month/{month}

curl "https://muslim.blue/wp-json/blue/v1/public/masjids/example-masjid/month/2026-11"

Example answer from /masjids/{slug}/month/{month}

{
  "masjid": {
    "slug": "example-listed-masjid",
    "name": "Example Listed Masjid",
    "tz": "America/New_York",
    "listed": true,
    "approximate": false,
    "page": "https://muslim.blue/example-listed-masjid/"
  },
  "times": "calculated",
  "notice": "This masjid has not published its own times on Muslim.Blue yet. These are calculated adhan times, and no iqamah is shown: iqamah times are published by the masjid.",
  "attribution": [],
  "month": "2026-11",
  "from": "2026-11-01",
  "to": "2026-11-30",
  "days": [
    {
      "date": "2026-11-06",
      "weekday": "Friday",
      "tz": "America/New_York",
      "hijri": {
        "day": 26,
        "month": 5,
        "year": 1448,
        "name": {
          "en": "Jumada al-Ula",
          "es": "Yumada al-Ula",
          "ar": "جمادى الأولى"
        },
        "method": "fcna"
      },
      "adhan": {
        "fajr": "05:38",
        "sunrise": "06:48",
        "dhuhr": "12:08",
        "asr": "15:05",
        "maghrib": "17:27",
        "isha": "18:38"
      },
      "iqamah": null,
      "note": "iqamah not published by this masjid",
      "jumuah": [],
      "eid": [],
      "taraweeh": null,
      "warnings": [],
      "built_at": "2026-11-06T04:00:00Z"
    }
  ]
}

A masjid that has not published its own times, so its times are calculated. One day shown; the answer has all 30.

GET `/masjids/{slug}/year`

A masjid's next 400 days no key needed

The coming 400 days from the masjid's today, for apps and screens that keep working offline. Send the ETag back in If-None-Match to get a 304 when nothing changed.

Parameters of /masjids/{slug}/year
Name	Where	What it is
`slug`	in the path	The masjid's address on Muslim.Blue, as in muslim.blue/{slug}. string

Example request to /masjids/{slug}/year

curl "https://muslim.blue/wp-json/blue/v1/public/masjids/example-masjid/year"

Example answer from /masjids/{slug}/year

{
  "masjid": {
    "slug": "example-masjid",
    "name": "Example Masjid",
    "tz": "America/New_York",
    "listed": false
  },
  "from": "2026-11-06",
  "to": "2027-12-10",
  "days": [
    {
      "date": "2026-11-06",
      "weekday": "Friday",
      "tz": "America/New_York",
      "hijri": {
        "day": 26,
        "month": 5,
        "year": 1448,
        "name": {
          "en": "Jumada al-Ula",
          "es": "Yumada al-Ula",
          "ar": "جمادى الأولى"
        },
        "method": "fcna"
      },
      "adhan": {
        "fajr": "05:38",
        "sunrise": "06:48",
        "dhuhr": "12:08",
        "asr": "15:05",
        "maghrib": "17:27",
        "isha": "18:38"
      },
      "iqamah": {
        "fajr": "06:15",
        "dhuhr": "13:15",
        "asr": "15:45",
        "maghrib": "17:32",
        "isha": "19:45",
        "source": {
          "fajr": "rule",
          "dhuhr": "rule",
          "asr": "rule",
          "maghrib": "rule",
          "isha": "rule"
        }
      },
      "jumuah": [
        {
          "slot": 1,
          "khutbah": "13:15",
          "iqamah": "13:45",
          "arrive": null,
          "language": "English",
          "place": "Main hall"
        }
      ],
      "eid": [],
      "taraweeh": null,
      "warnings": [],
      "built_at": "2026-11-06T04:00:00Z"
    }
  ]
}

One day shown; the answer has 400.

GET `/masjids/{slug}/prayer.ics`

A masjid's prayer times as a calendar no key needed

The coming days as an iCalendar (RFC 5545) feed, for calendar apps.

Parameters of /masjids/{slug}/prayer.ics
Name	Where	What it is
`slug`	in the path	The masjid's address on Muslim.Blue, as in muslim.blue/{slug}. string

Example request to /masjids/{slug}/prayer.ics

curl "https://muslim.blue/wp-json/blue/v1/public/masjids/example-masjid/prayer.ics"

Example answer from /masjids/{slug}/prayer.ics

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Muslim.Blue//Times//EN
CALSCALE:GREGORIAN
METHOD:PUBLISH
NAME:Example Masjid prayer times
X-WR-CALNAME:Example Masjid prayer times
X-WR-CALDESC:Iqamah\, Jumu'ah and Eid prayer times published by Example Masjid.
X-WR-TIMEZONE:America/New_York
REFRESH-INTERVAL;VALUE=DURATION:PT6H
X-PUBLISHED-TTL:PT6H
BEGIN:VEVENT
UID:20261106-fajr-m0@muslim.blue
DTSTAMP:20261106T040000Z
DTSTART;TZID=America/New_York:20261106T061500
DTEND;TZID=America/New_York:20261106T063500
SUMMARY:Fajr iqamah
DESCRIPTION:Adhan 5:38 AM. Iqamah 6:15 AM.
LOCATION:Example Masjid\, 100 Example Street\, Columbia\, SC 29201
END:VEVENT
END:VCALENDAR

One event shown; the calendar also carries its time zone and every prayer of each day.

Calculated times

GET `/times`

Calculated adhan times for any point key needed

Adhan times for any latitude and longitude, method and date (or a whole month). These are calculated times, never a masjid's iqamah times. Without a method, the method of the nearest masjid that publishes on Muslim.Blue is used, within 150 km, else ISNA in North America and the Muslim World League elsewhere. Needs a free key.

Parameters of /times
Name	Where	What it is
`lat`	required	Latitude, -90 to 90, up to 7 decimals. number
`lng`	required	Longitude, -180 to 180, up to 7 decimals. number
`tz`	required	The place's time zone, as an IANA name such as America/New_York. string
`date`	optional	One date, YYYY-MM-DD. Today in tz when neither date nor month is given. string
`month`	optional	A whole month instead of one date, YYYY-MM. string
`method`	optional	The calculation method. See /methods. isna, mwl, egyptian, umm_al_qura, karachi, tehran, gulf, kuwait, qatar, singapore, turkey, moonsighting, jafari
`asr`	optional	The Asr school: standard (shadow once its length) or hanafi (twice). standard, hanafi
`high_lat`	optional	The rule for Fajr and Isha far from the equator. Default middle. none, middle, seventh, angle
`hijri`	optional	The Hijri calendar for each day's date and for Ramadan. Default fcna. fcna, umm_al_qura, tabular

Example request to /times

curl -H "X-Api-Key: YOUR_KEY" "https://muslim.blue/wp-json/blue/v1/public/times?lat=34.0007&lng=-81.0348&tz=America%2FNew_York&date=2026-11-06&method=isna"

Example answer from /times

{
  "kind": "calculated",
  "notice": "Calculated adhan times for this point. They are not the iqamah times of any masjid.",
  "point": {
    "lat": 34.0007,
    "lng": -81.0348
  },
  "tz": "America/New_York",
  "method": {
    "key": "isna",
    "label": "ISNA (Fajr 15°, Isha 15°)",
    "asr_school": "standard",
    "high_lat": "middle",
    "chosen_by": "request",
    "masjid": null
  },
  "hijri": "fcna",
  "from": "2026-11-06",
  "to": "2026-11-06",
  "days": [
    {
      "date": "2026-11-06",
      "weekday": "Friday",
      "hijri": {
        "day": 26,
        "month": 5,
        "year": 1448,
        "name": {
          "en": "Jumada al-Ula",
          "es": "Yumada al-Ula",
          "ar": "جمادى الأولى"
        },
        "method": "fcna",
        "text": {
          "en": "26 Jumada al-Ula 1448",
          "ar": "٢٦ جمادى الأولى ١٤٤٨ هـ"
        },
        "month_start": "2026-10-12"
      },
      "adhan": {
        "fajr": "05:38",
        "sunrise": "06:48",
        "dhuhr": "12:08",
        "asr": "15:05",
        "maghrib": "17:27",
        "isha": "18:38"
      },
      "midnight": "23:32",
      "exact": {
        "fajr": "2026-11-06T05:37:42-05:00",
        "sunrise": "2026-11-06T06:48:18-05:00",
        "dhuhr": "2026-11-06T12:07:46-05:00",
        "asr": "2026-11-06T15:04:15-05:00",
        "maghrib": "2026-11-06T17:26:51-05:00",
        "isha": "2026-11-06T18:37:24-05:00",
        "midnight": "2026-11-06T23:32:41-05:00"
      },
      "estimated": []
    }
  ]
}

GET `/times/method`

The method people near a point use no key needed

The method of the nearest masjid that publishes on Muslim.Blue within 150 km, else ISNA in North America and the Muslim World League elsewhere. The point is rounded to two decimals.

Parameters of /times/method
Name	Where	What it is
`lat`	required	Latitude. number
`lng`	required	Longitude. number

Example request to /times/method

curl "https://muslim.blue/wp-json/blue/v1/public/times/method?lat=34.00&lng=-81.03"

Example answer from /times/method

{
  "method": {
    "key": "isna",
    "label": "ISNA (Fajr 15°, Isha 15°)",
    "asr_school": "standard",
    "high_lat": "middle"
  },
  "source": "north_america",
  "masjid": null,
  "point": {
    "lat": 34,
    "lng": -81.03
  }
}

GET `/methods`

Calculation methods and calendars no key needed

Every calculation method with its angles and intervals, the Asr schools, the high-latitude rules and the Hijri calendars.

Example request to /methods

curl "https://muslim.blue/wp-json/blue/v1/public/methods"

Example answer from /methods

{
  "methods": [
    {
      "key": "isna",
      "label": "ISNA (Fajr 15°, Isha 15°)",
      "fajr_angle": 15,
      "isha_angle": 15,
      "isha_minutes": 0,
      "isha_minutes_ramadan": 0,
      "maghrib_angle": 0,
      "method_adjust": {}
    },
    {
      "key": "mwl",
      "label": "Muslim World League (Fajr 18°, Isha 17°)",
      "fajr_angle": 18,
      "isha_angle": 17,
      "isha_minutes": 0,
      "isha_minutes_ramadan": 0,
      "maghrib_angle": 0,
      "method_adjust": {}
    }
  ],
  "asr_schools": [
    "standard",
    "hanafi"
  ],
  "high_latitude_rules": [
    "none",
    "middle",
    "seventh",
    "angle"
  ],
  "hijri": [
    {
      "key": "fcna",
      "label": "Calculated (Fiqh Council of North America)"
    },
    {
      "key": "umm_al_qura",
      "label": "Umm al-Qura (Makkah)"
    },
    {
      "key": "tabular",
      "label": "Tabular civil calendar"
    }
  ]
}

Two methods shown; the answer has them all.

Hijri date

GET `/hijri`

The Hijri date by method no key needed

The Hijri date of a Gregorian date by calculated FCNA, Umm al-Qura or the tabular civil calendar, with an offset of up to two days. A masjid that follows local sighting has its own Hijri date in its days.

Parameters of /hijri
Name	Where	What it is
`date`	optional	The Gregorian date, YYYY-MM-DD. Today in UTC by default. string
`method`	optional	fcna (the default), umm_al_qura or tabular. fcna, umm_al_qura, tabular
`offset`	optional	Days to move the calculated date, -2 to 2. integer

Example request to /hijri

curl "https://muslim.blue/wp-json/blue/v1/public/hijri?date=2026-11-06&method=umm_al_qura"

Example answer from /hijri

{
  "date": "2026-11-06",
  "method": "umm_al_qura",
  "method_label": "Umm al-Qura (Makkah)",
  "offset": 0,
  "hijri": {
    "day": 26,
    "month": 5,
    "year": 1448,
    "name": {
      "en": "Jumada al-Ula",
      "es": "Yumada al-Ula",
      "ar": "جمادى الأولى"
    },
    "method": "umm_al_qura",
    "text": {
      "en": "26 Jumada al-Ula 1448",
      "ar": "٢٦ جمادى الأولى ١٤٤٨ هـ"
    },
    "month_start": "2026-10-12"
  }
}

About the API

GET `/openapi.json`

This API as OpenAPI 3.1 no key needed

The OpenAPI 3.1 description of every route, made from the same list the API is limited and tested by.

Example request to /openapi.json

curl "https://muslim.blue/wp-json/blue/v1/public/openapi.json"

Example answer from /openapi.json

{
  "openapi": "3.1.0",
  "info": {
    "title": "Muslim.Blue API",
    "version": "1.0.0"
  },
  "paths": {
    "/masjids": {
      "get": {
        "operationId": "searchMasjids"
      }
    }
  }
}

One path shown.

Ramadan

GET `/masjids/{slug}/ramadan.json`

A masjid's Ramadan no key needed

Ramadan by the masjid's own calendar: its own decision on when Ramadan begins and ends, national statements shown as information only, each day's suhoor end (true dawn to the minute, never after the Fajr adhan, less the masjid's margin), iftar and taraweeh, with the suhoor end and iftar as instants for fasting reminders, the Eid al-Fitr prayers with their places, capacity, parking notes and the takbir time, when zakat al-fitr closes, and the printable timetable. A masjid that has not published on Muslim.Blue has calculated times only.

Parameters of /masjids/{slug}/ramadan.json
Name	Where	What it is
`slug`	in the path	The masjid's address on Muslim.Blue, as in muslim.blue/{slug}. string
`year`	optional	The Hijri year, such as 1448. Without it, the Ramadan under way, the coming one, or the one just ended while Eid lasts. integer

Example request to /masjids/{slug}/ramadan.json

curl "https://muslim.blue/wp-json/blue/v1/public/masjids/example-masjid/ramadan.json?year=1448"

Example answer from /masjids/{slug}/ramadan.json

{
  "version": 1,
  "masjid": {
    "slug": "example-masjid",
    "name": "Example Masjid",
    "tz": "America/New_York",
    "listed": false
  },
  "year": 1448,
  "phase": "coming",
  "today": "2027-01-20",
  "decision": {
    "method": "sighting",
    "ramadan": {
      "date": "2027-02-09",
      "confirmed": true,
      "source": "sighting",
      "body": "",
      "words": "local moon sighting"
    },
    "end": {
      "last": "2027-03-09",
      "days": 29,
      "settled": false
    },
    "fitr": {
      "date": "2027-03-10",
      "confirmed": false,
      "source": null,
      "body": "",
      "words": ""
    }
  },
  "statements": [
    {
      "kind": "ramadan",
      "date": "2027-02-08",
      "body": "Fiqh Council of North America",
      "url": "https://fiqhcouncil.org/",
      "note": ""
    }
  ],
  "margin": 10,
  "taraweeh": {
    "rakat": 8,
    "reciters": [],
    "minutes": 60,
    "qiyam": {
      "nights": [
        27,
        29
      ],
      "rule": "fixed",
      "time": "03:00",
      "before": null
    }
  },
  "eve": {
    "date": "2027-02-08",
    "taraweeh": {
      "starts": "21:15",
      "rakat": 8,
      "reciters": [],
      "night": 1,
      "qiyam": false,
      "minutes": 60,
      "qiyam_at": null
    }
  },
  "days": [
    {
      "date": "2027-02-09",
      "weekday": "Tuesday",
      "day": 1,
      "suhoor": "05:53",
      "fajr": "06:03",
      "iftar": "17:59",
      "isha": "19:15",
      "isha_iqamah": "21:00",
      "taraweeh": {
        "starts": "21:15",
        "rakat": 8,
        "reciters": [],
        "night": 2,
        "qiyam": false,
        "minutes": 60,
        "qiyam_at": null
      },
      "last_fast": false,
      "alerts": {
        "suhoor": "2027-02-09T10:53:00Z",
        "iftar": "2027-02-09T22:59:00Z"
      }
    }
  ],
  "eid": {
    "date": "2027-03-10",
    "takbir": "07:30",
    "shifts": [
      {
        "shift": 1,
        "starts": "08:00",
        "place": "Main hall",
        "capacity": 400,
        "parking": "Overflow parking at the school",
        "note": ""
      }
    ]
  },
  "fitr": {
    "closes_at": "2027-03-10T13:00:00Z",
    "prayer": "08:00",
    "settled": false
  },
  "print": {
    "letter": "https://muslim.blue/wp-json/blue/v1/public/masjids/example-masjid/ramadan?year=1448&paper=letter",
    "a4": "https://muslim.blue/wp-json/blue/v1/public/masjids/example-masjid/ramadan?year=1448&paper=a4"
  }
}

One day of Ramadan shown.

Masjid news and programs

GET `/masjids/{slug}/announcements`

A masjid's news no key needed

The announcements and newsletters the masjid sent to its followers, newest first, each with a short excerpt and its own page. A message sent only to members or to a program's registrants is never here. A masjid that has not published on Muslim.Blue answers an empty list.

Parameters of /masjids/{slug}/announcements
Name	Where	What it is
`slug`	in the path	The masjid's address on Muslim.Blue, as in muslim.blue/{slug}. string
`limit`	optional	How many messages to answer, 1 to 20. integer

Example request to /masjids/{slug}/announcements

curl "https://muslim.blue/wp-json/blue/v1/public/masjids/example-masjid/announcements?limit=2"

Example answer from /masjids/{slug}/announcements

{
  "masjid": {
    "slug": "example-masjid",
    "name": "Example Masjid"
  },
  "announcements": [
    {
      "id": 412,
      "kind": "announcement",
      "title": "Family night this Saturday",
      "excerpt": "Join us after Maghrib for dinner and a short talk. Everyone is welcome.",
      "sent_at": "2026-11-04T22:10:00Z",
      "url": "https://muslim.blue/news/example-masjid/412-k3y9qa/"
    }
  ]
}

One message shown.

GET `/masjids/{slug}/janazah`

A masjid's janazah notices no key needed

The janazah notices the family allowed on the masjid's website, until the prayer, each with only what the family allowed to be shown. Never cached: a notice the family withdraws is gone from the next answer.

Parameters of /masjids/{slug}/janazah
Name	Where	What it is
`slug`	in the path	The masjid's address on Muslim.Blue, as in muslim.blue/{slug}. string

Example request to /masjids/{slug}/janazah

curl "https://muslim.blue/wp-json/blue/v1/public/masjids/example-masjid/janazah"

Example answer from /masjids/{slug}/janazah

{
  "masjid": {
    "slug": "example-masjid",
    "name": "Example Masjid"
  },
  "notices": [
    {
      "id": 37,
      "title": "Janazah prayer",
      "name": "",
      "prayer": {
        "on": "2026-11-06",
        "time": "13:30",
        "after": "dhuhr",
        "place": "Example Masjid",
        "at": "2026-11-06T18:30:00Z",
        "words": "Fri, Nov 6 at 1:30 PM, after Dhuhr"
      },
      "burial": "",
      "condolences": "",
      "opening": null,
      "url": null
    }
  ]
}

GET `/masjids/{slug}/programs`

A masjid's programs and classes no key needed

The programs and classes open or coming, soonest first, as the masjid's programs page words them, each with its page to register.

Parameters of /masjids/{slug}/programs
Name	Where	What it is
`slug`	in the path	The masjid's address on Muslim.Blue, as in muslim.blue/{slug}. string

Example request to /masjids/{slug}/programs

curl "https://muslim.blue/wp-json/blue/v1/public/masjids/example-masjid/programs"

Example answer from /masjids/{slug}/programs

{
  "masjid": {
    "slug": "example-masjid",
    "name": "Example Masjid"
  },
  "page": "https://muslim.blue/example-masjid/programs/",
  "programs": [
    {
      "id": 88,
      "title": "Tajweed for adults",
      "kind": "class",
      "kind_name": "Class",
      "summary": "Eight Saturday mornings on the rules of recitation.",
      "dates": "Nov 7, 2026 to Dec 26, 2026",
      "place": "At the masjid",
      "ages": "Adults",
      "price": "Free",
      "seats": "12 seats left",
      "status": "open",
      "starts_on": "2026-11-07",
      "ends_on": "2026-12-26",
      "url": "https://muslim.blue/example-masjid/programs/88/"
    }
  ]
}

One program shown.

Errors

Every refusal is JSON with a code to act on, a message in plain words, and the status.

An error

{
  "code": "blue_api_bad_request",
  "message": "Give tz, the place's time zone, as a name such as America/New_York.",
  "data": {
    "status": 400,
    "field": "tz"
  }
}

Error codes
Status	Code	What it means
301	`blue_api_moved`	The masjid moved to another address. Location has it.
400	`blue_api_bad_request`	A parameter is missing or wrong; data.field names it. Masjid times routes may answer blue_times_bad_request.
401	`blue_api_key_needed`	This route needs a free key in the header.
401	`blue_api_bad_key`	The key is not one of ours. Check that you copied all of it; a key's old secret stops working when it is rotated.
403	`blue_api_key_off`	The key was turned off. Make a new one on your keys page.
404	`blue_times_no_masjid`	There is no public masjid at this address.
404	`blue_times_no_location`	The masjid has no map location yet, so it has no times.
429	`blue_api_rate_limited`	Over a limit. Wait the seconds in Retry-After.
500	`blue_api_failed`	Our mistake. It is never cached, so try again in a minute.

Credit and terms

Some masjid listings come from OpenStreetMap, under the Open Database License. Every answer about such a masjid carries the credit in the X-Data-Attribution header, with a Link header to the license. A masjid's day and month answers also carry it in an "attribution" list, and its calendar feed in the calendar's description. Show this credit wherever you show those facts, or anything worked out from them:

Contains information from OpenStreetMap, © OpenStreetMap contributors, available under the Open Database License (ODbL). https://www.openstreetmap.org/copyright

Using the API means agreeing to the API Terms of Use. What we keep about keys and their use is in the Privacy Notice.

API documentation

The basics

The address

Keys

Limits

Caching and ETags

Times

Published or calculated

The whole API in one file

Masjids

GET /masjids

GET /masjids/{slug}

Masjid times

GET /masjids/{slug}/today

GET /masjids/{slug}/day/{date}

GET /masjids/{slug}/days

GET /masjids/{slug}/month/{month}

GET /masjids/{slug}/year

GET /masjids/{slug}/prayer.ics