—
۞i-muslim

Developer API · v1

Build with i-muslim data

A clean JSON API for the things every Islamic app needs: prayer times, Qibla direction, the Hijri calendar, mosque listings, the Quran, and the major Hadith collections — read and write. Free for community use, rate limited per key, no marketing tracking. Issue a key, drop in a fetch call, ship.

What you can do

Getting a key

Request a key through the contact form with a one-sentence description of what you're building and which endpoints you need. Keys are issued manually during v1 and typically come back within 24 hours. Each key is scoped to a subset of resources (e.g. hadith, prayer-times) and a subset of permissions (read, write, delete).

Quick start

Every request needs the X-API-Key header. Here's the simplest possible request — Qibla bearing for London:

curl

curl -H "X-API-Key: im_live_..." \ "https://i-muslim.com/api/v1/qibla?lat=51.5074&lng=-0.1278"

JavaScript (Node 18+, browsers)

const res = await fetch( "https://i-muslim.com/api/v1/qibla?lat=51.5074&lng=-0.1278", { headers: { "X-API-Key": process.env.IMUSLIM_API_KEY } }, ); const { data } = await res.json(); console.log(data.bearing); // → 118.99 degrees from north

Python (requests)

import os, requests r = requests.get( "https://i-muslim.com/api/v1/qibla", params={"lat": 51.5074, "lng": -0.1278}, headers={"X-API-Key": os.environ["IMUSLIM_API_KEY"]}, ) print(r.json()["data"]["bearing"])

Free translation downloads

Bulk downloads of every translation in our data store, no API key required and CORS open to all origins. Cached at the edge for an hour. Each response carries the upstream attribution and licence so you know exactly what you can do with the text.

Important: the modern translator-authored translations (Saheeh International, Kuliev, Musayev, Diyanet, and the translator-credited Hadith renderings) are under translator copyright. Our endpoints return their provenance metadata (attribution, license, source_url) but not the text (text is null) — fetch the text directly from source_url. Arabic Quran (Uthmani mushaf) and Arabic Hadith editions are classical public-domain text and are returned in full.

curl https://i-muslim.com/api/v1/translations curl https://i-muslim.com/api/v1/translations/quran/ar curl https://i-muslim.com/api/v1/translations/quran/en/1 curl https://i-muslim.com/api/v1/translations/hadith/bukhari/ar

Want to contribute or correct a translation? Use the contact form with the subject “Translation contribution” — send the diff, the source, and the licence you're releasing it under, and we'll review and merge.

Publishing a translation

With a write-scope key, you can publish or update a translation for any hadith or Quranic ayah. The endpoint is idempotent — call it again with new text and it overwrites. Arabic (text_ar) is never editable via API.

curl -X PUT \ -H "X-API-Key: im_live_..." \ -H "Content-Type: application/json" \ -d '{"text": "The deeds are only by intentions..."}' \ "https://i-muslim.com/api/v1/hadith/collections/bukhari/hadiths/1/translations/en"

Every write is recorded in our audit log with your key id, your key name, and a before/after snapshot. If you push a translation that turns out to be wrong, we can roll it back.

Endpoints

Read (GET)

Browser-callable: Access-Control-Allow-Origin: * is set on every response. Safe to call directly from frontend code if your key is read-only.

Write (PUT / PATCH / POST)

Server-side only.Write endpoints intentionally don't set CORS headers — call them from your backend so the key never lands in a browser. Requires write permission on the key.

Authentication

Send your key in the X-API-Key header on every request. Keys look like im_live_AbCd… and are shown exactly once when issued — store them in your secrets manager (Vercel env vars, AWS Secrets Manager, GitHub Actions secrets, etc.). We only keep a SHA-256 hash on our side, so we cannot recover a lost key — ask for a new one.

Rate limits

100 requests per minute, per key. Every response carries three headers so you can self-throttle:

X-RateLimit-Limit: 100 X-RateLimit-Remaining: 87 X-RateLimit-Reset: 1747234260

When you exceed the limit you'll get 429 Too Many Requests with error code RATE_LIMITED. Wait for the reset timestamp, or contact us if you need a higher cap for a legitimate use case.

Response shape

// Success { "data": { "bearing": 118.99, "origin": {...}, "kaaba": {...} } } // Error { "error": { "code": "INVALID_API_KEY", "message": "API key not found or revoked" } }

Error codes

Stability & versioning

v1 is the stable surface. Any breaking change ships as v2 on a new path; we'll keep v1 running for at least 12 months after v2 launches.

Attribution & ethics

Quran and Hadith are sacred — please render them faithfully, don't paraphrase, and don't silently truncate. If you publish translations you authored, please make sure you have the right to do so. If you spot a translation error in our data, let us know and we'll roll it back.

Contact

Questions, bug reports, or higher-quota requests — please use the contact form and mention “Developer API” in the subject.