Getting started

Base URL and format

Every endpoint lives under https://islamenc.com/api and answers JSON. There is no API key and nothing to sign; a plain GET is enough. Responses are UTF-8, and Arabic comes back exactly as the source has it: Quranic text in Uthmani script with its marks, and in standard (imla’i) spelling beside it where the endpoint offers both.

curl -s "https://islamenc.com/api/languages" | head -c 300

[{"isoCode":"aa","arabicName":"عفري","englishName":"Afar","nativeName":"Qafár af","direction":"ltr"}, ...

Languages

Languages are named by ISO code (en, fr, bn, prs…). GET /languages lists the 147 the platform knows, each with its names and writing direction. Not every book, card or surah exists in every language: ask a book for /languages, an encyclopedia for /card-languages, and the Quran for /translation-keys before you request a language.

Most endpoints take lang:

On listings it adds the translated title or description where one exists (/books?lang=fr), or restricts the count to that language (/enc?lang=en).
On content it selects the translation (/quran/surahs/2?lang=fr, /enc/cards/7913?lang=en). The Arabic original always comes along.

Arabic is the source language of everything, so lang=ar, or no lang at all, is always complete.

Identifiers

Thing	Identifier	Example
Surah	`surah_no`, 1 to 114	`2`
Aya	`surah_no` and `aya_no`	surah `2`, aya `255`
Book	`project_id`	`36`
Book version	`version_name`	`2.0`
Encyclopedia	`external_id`	`101` is the hadith encyclopedia
Card	`external_id`	`7913`
Category	`"<table>:<item>"`	`11:2` is “الحديث وعلومه” in the sharia classification
Property value	`"<table>:<item>"` under a property id `t<table>`	`t40` = `40:1` is a short card

All of them are stable: a card keeps its external_id across versions, and a book its project_id across editions.

Pagination

Two styles, depending on the endpoint:

Page and limit on the card listing: GET /enc/101/cards?page=2&limit=20 answers { "cards": [...], "total": 839 }. limit is at most 100. Without page the whole set comes back in one answer, which is what the site itself uses, and is a few megabytes for the hadith encyclopedia.
Offset and limit on the search endpoints: GET /hybrid-search?q=...&offset=10&limit=10. limit is at most 50 and offset + limit at most 1000. hasMore (with format=hits) says whether another page exists.

The Quran, the catalogue and the languages have no pages: a surah, the book list or the language list comes whole.

Errors

The API uses HTTP status codes and a small JSON body:

{ "statusCode": 404, "message": "Book 999 not found" }

Status	When
`400`	A parameter is missing or malformed (`q` absent, `type` unknown, a limit out of range). The `message` says which.
`404`	The surah, book, version, card or language does not exist, or the book has been withdrawn.
`429`	More than 10 requests a second from one address. Slow down and retry after a moment.
`500` / `502` / `503`	Something failed on our side or the API is restarting. Retry with backoff.

A missing book detail (GET /books/{projectId}) currently answers 200 with an empty body rather than 404; check for an empty response.

Rate limit and caching

Ten requests a second per IP address, with room for short bursts of up to forty. That is plenty for a page that loads a surah and a few cards, and for a crawler that walks the catalogue politely. If you need sustained higher volume, tell us what you are building.

Every answer that can be cached says so: Cache-Control: public, max-age=600, stale-while-revalidate=3600. Content is synchronised from the source platform a few times a week, so caching answers for an hour on your side costs nothing in freshness. The two heaviest answers, a whole encyclopedia’s cards and the book catalogue, are cached by the API itself and come back in milliseconds once warm.

Calling from a browser

CORS is open, so the API can be called straight from client-side code:

const q = encodeURIComponent("فضل الصدقة");
const res = await fetch(`https://islamenc.com/api/hybrid-search?q=${q}&limit=5&lang=en`);
const { results } = await res.json();

Remember to encodeURIComponent Arabic query strings and field names (fields=متن الحديث on the card listing) before putting them in a URL.

What the API does not do

No writing: nothing here creates, edits or deletes content. Content comes from the source platform (ICADB and QuranEnc) and is synchronised a few times a week.
No accounts, favourites or user state.
No audio: the Quran is text and translations only.