Quran Readings API · v1

The Quran in all ten readings, through one API

Composed text for the twenty recitations (الروايات) of the ten readings (القراءات), with the differences between them marked word by word. Built for apps, websites and research.

Get your API credentials Read the API docs

No account yet? Request access · [email protected]

Request
GET /api/v1/chapters/1/text?readingId=2&recitationId=3&countingId=1&compareWithHafs=true

Warsh compared with Hafs

مَلِكِ يَوْمِ الدِّينِ

Response

{
  "chapterId": 1,
  "readingId": 2,
  "recitationId": 3,
  "comparedWith": { "readingId": 1, "recitationId": 1, "wayId": 0 },
  "text": "بِسْمِ اللَّهِ …",
  "highlights": [
    { "start": …, "length": …, "type": "TwoRecitationDifference" }
  ],
  "words": [{ "start": 0, "wSequenceId": 1, … }]
}
readings
10
readings
recitations
20
recitations
chapters
114
chapters
verse-counting systems
6
verse-counting systems

Everything the reading needs, as data

The same engine as the reader on quran.iilm.io, open to your own applications.

Composed text per recitation

Any chapter in any of the twenty recitations, with stop marks, sajdah and rubʿ marks and verse numbers, in the verse-counting system you choose.

Differences, highlighted

Compare with Hafs or with any recitation, show farsh words, positions where the readings differ and Kufi counting differences. Each comes back as a span you can style.

Word-level readings

Pick a word and get what every recitation reads at that position, grouped by shared wording.

Accompanying texts

Tafseer, translations and other texts, by chapter, by verse or by word position.

Research endpoints

Search words by prefix, count word frequencies and list the words that differ from Hafs, per chapter or for the whole Quran.

Standard and secure

OAuth 2.0, an OpenAPI 3 document, RFC 9457 error responses and per-application rate limits.

From zero to your first request in three steps

  1. 1

    Register your application

    Create an application in the developer portal. A server application receives a client_id and a client_secret, shown once: keep the secret on your server.

    Open the developer portal
  2. 2

    Get an access token

    POST your credentials to /connect/token with grant_type=client_credentials and scope=quran.read. The token is valid for 60 minutes: reuse it until it expires.

  3. 3

    Call the API

    Send the token as Authorization: Bearer <token> to any /api/v1 endpoint. Every response is JSON.

    Browse the endpoints

Copy, paste, run

Al-Fatiha in the recitation of Warsh, with the words that differ from Hafs highlighted.

# 1. Get an access token (valid for 60 minutes)
curl -s -X POST https://quran-api.iilm.io/connect/token \
  -d grant_type=client_credentials \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d scope=quran.read

# 2. Al-Fatiha in Warsh, with the differences from Hafs highlighted
curl -s "https://quran-api.iilm.io/api/v1/chapters/1/text?readingId=2&recitationId=3&countingId=1&compareWithHafs=true" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Keep the client secret on a server. Never put it in a web page or a mobile app.

The reading endpoints

All of them need the quran.read scope. Every parameter and response is documented, with a console to try requests.

See every parameter in the API docs

Catalog

Text

Accompanying texts

Research

Pick the flow that fits your app

Servers and back ends

Client credentials

  • A confidential client with a client_id and a client_secret
  • Scope quran.read: read everything, no user involved
  • Best for websites that render on the server, bots and data pipelines

Apps where people sign in

Authorization code + PKCE

  • A public client with registered redirect URIs, no secret
  • People sign in on the API; the scopes follow their role
  • Best for mobile apps and single-page web apps
Access tokens
JWT, 60 minutes
Refresh tokens
14 days (sign-in flow)
Rate limit
600 requests / minute per app
Errors
RFC 9457 problem details
OAuth discovery document

Questions

How do I get access?

Register your application in the developer portal. If you don’t have an account yet, email us with a few lines about your project and we will set you up.

Which readings and recitations are included?

The ten readings with two recitations each (twenty recitations), all 114 chapters and six verse-counting systems. GET /api/v1/readings and /api/v1/recitations list them with the ids the other endpoints take.

Can I call the API from a browser or a mobile app?

Yes, but never with a client secret. Either register a public client and let people sign in with the authorization code flow and PKCE, or call the API from your own server and pass the results on.

What are the limits?

600 requests per minute for each application, and 30 per minute per IP address on the token endpoint. Over the limit the API answers 429. Reuse each token for its 60 minutes and cache chapter texts: the API allows it for 5 minutes.

How do I use highlights and word positions?

Each highlight has a start, a length and a type, measured in UTF-16 code units: the string indices of JavaScript, Java, C# and Swift’s NSString. Wrap those ranges in your own styles; the word positions let you ask for the readings of the word a person taps.

Is there an OpenAPI document?

Yes, at /openapi/v1.json on the API. Import it into Postman or Insomnia, or generate a typed client for your language.

Building something with the Quran?

Questions, access requests, partnerships or a reading you need: write to us.

[email protected] Get API key