Developer API

Every endpoint is a GET request that returns JSON. The base URL is:

https://islamicevents.app/api/v1

You need an API key. Replace YOUR_API_KEY below with yours.

Most integrations need only two calls. First, find your mosque's id:

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://islamicevents.app/api/v1/mosques?q=example"

Then fetch its upcoming events:

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://islamicevents.app/api/v1/mosques/MOSQUE_ID/events?limit=20"

Or from JavaScript on your server:

const res = await fetch(
  "https://islamicevents.app/api/v1/mosques/MOSQUE_ID/events?limit=10",
  { headers: { "X-API-Key": process.env.ISLAMIC_EVENTS_API_KEY } }
)
const { mosque, data: events } = await res.json()

for (const event of events) {
  const when = new Date(event.starts_at).toLocaleString()
  console.log(`${when} — ${event.title} (${event.url})`)
}

Can't find your mosque? It may not be listed yet. You can still use /events with a location filter.

Every request must include an API key. Send it in the X-API-Key header:

X-API-Key: YOUR_API_KEY

Or as a bearer token: Authorization: Bearer YOUR_API_KEY. Requests without a valid key get a 401 error.

Keys are free and issued by the Islamic Events team. Request a key below. Use one key per app or website.

• Keep your key private. Call the API from your server, not from code that runs in your visitors' browsers, where anyone can read the key.
• We count the requests made with each key. Keys that are misused can be revoked.
• If your key leaks, ask us for a new one and we'll revoke the old one.

Wherever you show data from the API, you must credit Islamic Events App and show the website islamicevents.app. Both must be visible to your users, next to the events. On the web, link to the website:

<p>
  Events from Islamic Events App ·
  <a href="https://islamicevents.app">islamicevents.app</a>
</p>

In a mobile app or on a screen where links aren't possible, show the same text: Events from Islamic Events App · islamicevents.app. We may revoke keys that are used without this credit.

Tell us who you are and what you're building. We review every request and email your key to you. You can also email admin@islamicevents.app.

Returns mosques sorted by name. Use it to look up the id of a mosque.

Response: { "data": [Mosque, …], "pagination": { … } }

Response: { "data": Mosque }. Returns 404 if the id is unknown or isn't a UUID.

Returns upcoming events at the mosque, earliest first. Accepts all of the event filters except mosque_id. The response also contains the mosque itself:

{
  "mosque": {
    "id": "1b3e…",
    "name": "Example Mosque",
    "website_url": "https://example-mosque.org",
    "address": "1 Example Road",
    "city": "London",
    "postcode": "E1 1AA",
    "country": "United Kingdom",
    "lat": 51.517,
    "lng": -0.065
  },
  "data": [
    {
      "id": "7f2c…",
      "slug": "tafsir-class-7f2c1a9e",
      "url": "https://islamicevents.app/events/tafsir-class-7f2c1a9e",
      "title": "Tafsir class",
      "description": "Weekly tafsir of Surah al-Kahf.",
      "category": "lecture",
      "audience": "all",
      "starts_at": "2026-10-09T18:00:00+00:00",
      "ends_at": "2026-10-09T19:30:00+00:00",
      "venue_type": "venue",
      "location": { "name": "Main hall", "address": null, "lat": 51.517, "lng": -0.065 },
      "image_url": null,
      "image_position": 50,
      "source_url": "https://example-mosque.org/events",
      "is_featured": false,
      "series_id": "7f2c…",
      "recurrence": { "rule": "weekly", "days": [5], "week_of_month": null, "until": null },
      "mosque": { "id": "1b3e…", "name": "Example Mosque", "…": "…" }
    }
  ],
  "pagination": { "limit": 20, "offset": 0, "total": 14 }
}

Returns upcoming events across all mosques and organisers, earliest first. This includes events that aren't linked to a mosque, whose mosque is null.

Response: { "data": [Event, …], "pagination": { … } }

Example: online sisters' events in November:

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://islamicevents.app/api/v1/events?audience=sisters&venue_type=online&from=2026-11-01&to=2026-11-30T23:59:59Z"

Example: events within 10 km of a point:

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://islamicevents.app/api/v1/events?lat=51.5072&lng=-0.1276&radius=10"

/events and /mosques/{id}/events accept these query parameters. Combine them as you like.

• Dates can be a date (2026-11-01) or a date and time with a UTC offset (2026-11-01T18:00:00Z).
• Results are always sorted by start time, including on radius searches.
• Radius searches only return events that have coordinates.

Look up an event by its id or slug. Unlike the lists, this also returns past events. Response: { "data": Event }.

Returns the mosque's daily prayer timetable: begin and jamaat times for the five prayers, sunrise, and the Jumu'ah times in effect each day. mosque_id is required. Without it you get a 400. With no dates you get today.

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://islamicevents.app/api/v1/prayer-times?mosque_id=MOSQUE_ID&from=2026-10-01&to=2026-10-31"

{
  "mosque": { "id": "1b3e…", "name": "Example Mosque", "…": "…" },
  "data": [
    {
      "date": "2026-10-09",
      "fajr": { "begins": "05:46", "jamaat": "06:15" },
      "sunrise": "07:17",
      "dhuhr": { "begins": "12:56", "jamaat": "13:30" },
      "asr": { "begins": "15:52", "jamaat": "16:15" },
      "maghrib": { "begins": "18:26", "jamaat": "18:31" },
      "isha": { "begins": "19:51", "jamaat": "20:00" },
      "jumuah": ["13:15", "13:45"],
      "source_url": "https://example-mosque.org/prayer-times",
      "updated_at": "2026-10-06T03:00:12+00:00"
    }
  ],
  "range": { "from": "2026-10-09", "to": "2026-10-09" }
}

• We read the times from each mosque's own published timetable, daily. Days the timetable doesn't cover aren't returned, so data can be shorter than the range or empty.
• Times are local to the mosque, exactly as printed. They have no time zone.

A recurring event, such as a weekly class, is returned once per occurrence. Each occurrence has its own id, slug and times. All occurrences share the same series_id, so you can group them. The recurrence object describes the pattern:

List endpoints return a pagination object with the limit and offset you used and the total number of matching results. To get the next page, add limit to offset.

async function allEvents(mosqueId) {
  const events = []
  let offset = 0
  while (true) {
    const res = await fetch(
      `https://islamicevents.app/api/v1/mosques/${mosqueId}/events?limit=100&offset=${offset}`,
      { headers: { "X-API-Key": process.env.ISLAMIC_EVENTS_API_KEY } }
    )
    const page = await res.json()
    events.push(...page.data)
    offset += page.data.length
    if (page.data.length === 0 || offset >= page.pagination.total) return events
  }
}

Errors use the matching HTTP status code and this body:

{ "error": { "code": "bad_request", "message": "limit must be an integer between 1 and 100" } }

• Cache responses on your side and don't request the same data more than about once a minute.
• When you show an event, link to its url so people can see the full and latest details.
• Credit Islamic Events App and show islamicevents.app wherever the data appears. See Attribution.
• Event details and images belong to their organisers. See our Terms of Use.
• We may add new fields and categories to v1, so ignore any you don't recognise.