Is the Quran API free to use?

Verse, chapter, and passage lookups and quote search do not need an API key. Search works on the free tier with a daily limit. The Starter plan is $5 per month for 3,000 searches, and the API plan is $39 per month for 30,000 searches.

Which Quran text and translation does it return?

Each verse includes Arabic text and an English translation. Lookup responses include an edition field, so you can display the translation's details next to the text.

Can I search the Quran in Arabic?

Yes. Search accepts Arabic, English, or mixed-language queries, and it also accepts references such as 2:255.

Does the Quran API include Tafsir?

Yes. Add tafsir to the indexes parameter to search five Tafsir editions alongside the verses. Tafsir results use the same JSON shape as Quran results.

Can I use it to ground an AI chatbot?

Yes. Call search from your backend, pass the returned sources to your own model, and keep the references for citations. POST /v1/chat does the same with hosted generation, and the MCP server exposes the sources to MCP hosts.

What are the rate limits?

Each API key has a per-minute limit set by its plan: 60 requests per minute on Starter and 120 on the API plan. Anonymous search and public lookups are limited per client. Back off and retry after an HTTP 429.

Quran API

Quran API for Search, Tafsir, and Citations

Read any verse, chapter, or passage by reference. Search the Qur'an and Tafsir by meaning, keyword, or reference. Each result comes back as JSON with the reference, Arabic text, translation, and edition metadata, ready for a citation card.

Read the Search Docs View API Plans

Base URL: https://api.madeenan.com/v1
Quran Coverage: 6,236 verses, Arabic with an English translation
Tafsir: 31,180 passages from five editions in Arabic and English
Access: Verse lookups are public. Search works anonymously within free limits or with an API key.

Reference Lookups Stay Simple

When your app already knows the reference, ask for it directly. GET /v1/quran/2:255 returns one verse, /v1/quran/chapter/112 returns a surah, and /v1/quran/passage/94/5-6 returns a bounded range. These reads need no key and are cacheable, so a reading screen or a verse-of-the-day card stays fast.

Each response carries the verse key, surah and ayah numbers, Arabic text, translation, and an edition field. Show the edition with the text so readers know which translation they are reading.

Search When the User Asks a Question

Most users do not type 2:153. They type 'patience when things go wrong'. GET /v1/search combines meaning-based and keyword retrieval, and a query that looks like a reference resolves as one. Queries can be Arabic, English, or a mix of both.

Results come back grouped by corpus with a score and metadata. Ask for indexes=quran,tafsir and the explanation arrives next to the verse it explains, in the same response.

Tafsir in the Same Payload

The Tafsir index covers Tafsir Muyassar and Tafsir as-Sa'di in Arabic, and Ibn Kathir, al-Jalalayn, and Ma'arif-ul-Quran in English. Tafsir results use the same result shape as verses, so one source-card component can render both.

Tafsir is commentary, not the text of the Qur'an. Label it that way in your interface, and keep the edition name visible.

Ready for AI Features

If you are building an assistant, search first, then pass the returned sources to your own model from your backend. Keep the references so every claim in the answer points to a verse your user can open. If you prefer, POST /v1/chat runs retrieval and hosted generation and returns citations. The same tools are available to MCP hosts through the Madeenan MCP server.

Endpoints

All endpoints live under https://api.madeenan.com. Send an API key in the X-Madeenan-API-Key header from your server. The full schema is in the API reference.

Endpoint	Access	Use
GET /v1/quran/{verse_key}	Public	One verse, for example 2:255.
GET /v1/quran/chapter/{surah_number}	Public	A full surah, 1 to 114.
GET /v1/quran/passage/{surah_number}/{start-end}	Public	A bounded ayah range, for example 94/5-6.
GET /v1/search	Anonymous or API key	Search quran, tafsir, hadith, and dua indexes by meaning, keyword, or reference.
POST /v1/quote-search	Public	Check where a piece of wording appears.
POST /v1/chat	API key	Hosted answer generation with citations.

Examples

The TypeScript and Python clients are prepared for npm and PyPI but are not published yet. Until they are, call the REST endpoints directly; they are plain HTTPS and JSON.

Read a Verse

No key needed. The response includes an edition field.

$curl "https://api.madeenan.com/v1/quran/2:255"

Read a Passage

Request a bounded ayah range when one verse is not enough context.

$curl "https://api.madeenan.com/v1/quran/passage/94/5-6"

Search the Quran and Tafsir

Send the API key from your server. limit_per_source accepts 1 to 25.

$curl "https://api.madeenan.com/v1/search?q=patience%20in%20hardship&indexes=quran,tafsir&limit_per_source=5" \

-H "X-Madeenan-API-Key: $MADEENAN_API_KEY"

TypeScript

The typed client wraps the same endpoints.

import { MadeenanClient } from "@madeenan/sdk";

const client = new MadeenanClient({

apiKey: process.env.MADEENAN_API_KEY,

});

const results = await client.search({

q: "patience in adversity",

indexes: ["quran", "hadith"],

limit_per_source: 3,

});

for (const source of results.results.quran ?? []) {

console.log(source.ref, source.translation);

}

const verse = await client.quran("2:153");

console.log(verse.ref, verse.edition);

Python

Sync and async clients share the same methods.

from madeenan_sdk import MadeenanClient, AsyncMadeenanClient

with MadeenanClient() as client:

results = client.search("patience", indexes=["quran", "hadith"])

for source in results.results.get("quran", []):

print(source.ref, source.translation)

# Inside your application's async function:

async def read_source():

async with AsyncMadeenanClient() as client:

verse = await client.quran_verse("2:153")

return verse

What It Does Not Do

One English translation edition. If you need many translations or languages, a dedicated Quran content API is the better fit.
No recitation audio endpoint for the Qur'an.
No word-by-word morphology or root data.
Search ranking is measured, not perfect. The public baseline reports its recall and failure rates.

How It Compares

Several good Quran APIs exist, and they solve different problems. This table compares what each one is built for, based on each project's public documentation.

Need	Madeenan	Quran Foundation Content API	fawazahmed0/quran-api
Built For	Source search and citations across Quran, Tafsir, Hadith, and duas	Quran.com content: translations, tafsir, audio, and user features	Free static Quran editions and translations
Reference Lookup	Verse, chapter, and passage	Yes	Yes, plus juz, page, and other divisions
Search	Meaning, keyword, and reference search	Search endpoint and SDK client	No search endpoint; static JSON files
Translations	Arabic plus one English translation	Many translations	Hundreds of translations in 90+ languages
Tafsir	Five editions, searchable	Available	Not included
Hadith and Duas	Same API and result shape	Not part of the Content API	A separate hadith-api project
Recitation Audio	Not offered	Available	Not included
Access	Public lookups; API key for search volume and chat	App credentials issued by Quran Foundation	No key; served from the jsDelivr CDN
Cost	Free tier; paid plans from $5 per month	See Quran Foundation's terms	Free, Unlicense

Checked in October 2026 against each project's public documentation. Terms change, so confirm them before you build on any API. Many apps use a content API for reading and Madeenan for search and citations.

Sources: Quran Foundation API documentation, fawazahmed0/quran-api on GitHub

Plans and Limits

Lookups are public. Search and hosted chat count against your plan. You pay any model provider you call from your own backend directly.

Free

$0 per month

10 searches/day
No hosted chat
No API key access
Source search for evaluation

Starter

$5 per month

3,000 searches/month
API key access
Source retrieval and citation payloads
100 hosted chat answers/month
60 requests per minute per key

API / Organization

$39 per month

30,000 searches/month included
API key access
Source retrieval and citation payloads
500 hosted chat answers/month
For B2B product integration
120 requests per minute per key

See pricing for current plans and rate limits for retry guidance.

Questions Developers Ask

Is the Quran API free to use?: Verse, chapter, and passage lookups and quote search do not need an API key. Search works on the free tier with a daily limit. The Starter plan is $5 per month for 3,000 searches, and the API plan is $39 per month for 30,000 searches.
Which Quran text and translation does it return?: Each verse includes Arabic text and an English translation. Lookup responses include an edition field, so you can display the translation's details next to the text.
Can I search the Quran in Arabic?: Yes. Search accepts Arabic, English, or mixed-language queries, and it also accepts references such as 2:255.
Does the Quran API include Tafsir?: Yes. Add tafsir to the indexes parameter to search five Tafsir editions alongside the verses. Tafsir results use the same JSON shape as Quran results.
Can I use it to ground an AI chatbot?: Yes. Call search from your backend, pass the returned sources to your own model, and keep the references for citations. POST /v1/chat does the same with hosted generation, and the MCP server exposes the sources to MCP hosts.
What are the rate limits?: Each API key has a per-minute limit set by its plan: 60 requests per minute on Starter and 120 on the API plan. Anonymous search and public lookups are limited per client. Back off and retry after an HTTP 429.
Is there a JavaScript or Python SDK?: The TypeScript and Python clients are prepared for npm and PyPI but are not published yet. Until they are, call the REST endpoints directly; they are plain HTTPS and JSON.