Quranpedia API v1 — Documentation

# Usage Policy — please read before integrating

The API is free — for apps, websites, bots, and research tools that query it live. No authentication, no fees. We want this content to reach as many people as possible.

1 · Attribution — optional for apps, required for republished dumps. Apps, websites, and bots that query the API live do not have to credit us — a visible link to https://quranpedia.net is appreciated but never required, and we will happily feature your project on the “Built with Quranpedia” page (email us!). Attribution is required only when publishing the data itself — in full or in part — as a downloadable database or dataset (public datasets, bulk dumps, mirrors) rather than inside an app: such publications must credit Quranpedia.net as the source with a link. The tafsir texts, translations, qiraat data, and metadata served here were collected, structured, and corrected by our team over many years.

2 · Do not bulk-scrape and republish. This API is not a download service. Our content is continuously corrected — Quranic ḍabṭ (diacritics), qiraʾat details, tafsir texts, and translations receive fixes every week. A copy scraped today silently drifts from the corrected text, and for Quranic content, redistributing a stale copy harms every downstream reader. Crawling millions of endpoints to mirror the corpus is therefore both wasteful and — more importantly — produces an outdated, uncorrectable copy.

3 · Rate limits. Requests are limited per IP to 120/minute and 10,000/day — far above what any real app needs, and far below what mirroring the corpus requires. Exceeding the limit returns 429 with a link back to this policy:

{
  "error": "Too many requests.",
  "message": "The Quranpedia API is free for apps and integrations, but it is not meant for bulk scraping...",
  "usage_policy": "https://quranpedia.net/api-docs#usage-policy",
  "contact": "[email protected]"
}

4 · Need the full dataset? Don’t scrape — download the official versioned dumps (gzipped JSON with SHA-256 checksums), then stay current with the changes endpoint. For datasets not covered by the dumps, email [email protected]. If you run a high-volume client, include a contact address in your User-Agent so we can reach you instead of blocking you.

In short: build on the API live and credit Quranpedia — don’t freeze a copy of a text that is still being corrected.

# Mushafs

Response

[
  {
    "id": 1,
    "name": "مصحف حفص",
    "description": "...",
    "image": "https://api.quranpedia.net/front/assets/img/mushafs/hafs.png",
    "bismillah": "﷽",
    "font_file": "https://api.quranpedia.net/assets/fonts/hafs/hafs.woff2",
    "images": "https://api.quranpedia.net/api-quran-svg/hafs.zip",
    "images_png": "https://api.quranpedia.net/api-quran-png/hafs.zip",
    "rawi": {
      "id": 1,
      "name": "حفص",
      "full_name": "حفص عن عاصم",
      "qiraa": {
        "id": 1,
        "name": "عاصم",
        "count": { "id": 1, "name": "متواترة" }
      }
    }
  }
]

Parameters

id integer required Mushaf ID

Response

{
  "id": 1,
  "name": "مصحف حفص",
  "description": "...",
  "image": "hafs.png",
  "bismillah": "﷽",
  "font_file": "https://api.quranpedia.net/assets/fonts/hafs/hafs.woff2",
  "images": "https://api.quranpedia.net/api-quran-svg/hafs.zip",
  "images_png": "https://api.quranpedia.net/api-quran-png/hafs.zip",
  "rawi": { "id": 1, "name": "حفص", "full_name": "حفص عن عاصم", "qiraa": { ... } },
  "surahs": [
    {
      "id": 1,
      "name": "الفاتحة",
      "coded_name": "...",
      "ayahs": [
        {
          "id": 1, "number": 1, "surah": 1, "page_number": 1,
          "text": "بِسْمِ اللَّهِ الرَّحْمَٰنِ الرَّحِيمِ",
          "marker": "...",
          "options": ["tafsir", "meanings", "similar", "topics", "fatwa", ...],
          "number_in_hafs": [1]
        }
      ]
    }
  ]
}

# Ayahs

Parameters

mushaf_id integer required Mushaf ID (e.g. 1 for Hafs)

surah_id integer required Surah number (1-114)

ayah_number integer optional Ayah number. Omit to get all ayahs.

Response

// Single ayah: GET /mushafs/1/1/1
{
  "id": 1,
  "number": 1,
  "surah": 1,
  "page_number": 1,
  "text": "بِسْمِ اللَّهِ الرَّحْمَٰنِ الرَّحِيمِ",
  "marker": "...",
  "options": ["tafsir", "meanings", "similar", "topics", "fatwa", "e3rab", "notes", "asbab", "translations"],
  "number_in_hafs": [1]
}

// All ayahs: GET /mushafs/1/1 → returns array of the above

Parameters

surah_id integer required Surah number (1-114)

ayah_number integer required Ayah number

Response

{
  "id": 1,
  "number": 1,
  "surah": 1,
  "page_number": 1,
  "text": "بِسْمِ اللَّهِ الرَّحْمَٰنِ الرَّحِيمِ",
  "marker": "...",
  "options": ["tafsir", "meanings", "similar", "topics", "fatwa", "e3rab", "notes", "asbab", "translations"]
}

Parameters

surah_id integer required Surah number

ayah_number integer required Ayah number

book_id integer required Book ID

Response

{
  "book": {
    "id": 1,
    "name": "تيسير التفسير",
    "short_name": "القطان",
    "language": { "id": 1, "name": "العربية", "code": "ar", "direction": "rtl" },
    "parts": 1,
    "author": { "id": 1050, "ar_name": "إبراهيم القطان", "full_name": "إبراهيم القطان" },
    "mohaqeq": null, "introducer": null, "reviewer": null, "translator": null
  },
  "content": [
    { "text": "...", "part": 1, "page": 5, "ayahs": "1:1-1:7" }
  ]
}

# Translations

Parameters

surah_id integer required Surah number

ayah_number integer required Ayah number

Response

[
  { "id": 2, "name": "الإنجليزية", "en_name": "English", "local_name": "English", "code": "en", "direction": "ltr" },
  { "id": 3, "name": "الفرنسية", "en_name": "French", "local_name": "Français", "code": "fr", "direction": "ltr" },
  { "id": 4, "name": "الإسبانية", "en_name": "Spanish", "local_name": "Español", "code": "es", "direction": "ltr" }
]

Parameters

surah_id integer required Surah number

ayah_number integer required Ayah number

language string optional Language code (e.g. "en", "fr"). Omit for all.

Response

// GET /translations/1/1/en
[
  {
    "book": {
      "id": 1947,
      "name": "Saheeh International",
      "short_name": "Saheeh",
      "authors": [{ "id": 123, "ar_name": "..." }]
    },
    "translation-content": "In the name of Allah, the Entirely Merciful, the Especially Merciful."
  }
]

// GET /translations/1/1 (all languages) → grouped by language code
{
  "en": [{ "book": { ... }, "translation-content": "..." }],
  "fr": [{ "book": { ... }, "translation-content": "..." }]
}

Parameters

language_code string optional Language code (e.g. "en"). Omit for all.

Response

[
  {
    "id": 1947,
    "name": "Saheeh International",
    "short_name": "Saheeh",
    "card": "Description of the book...",
    "content": "https://api.quranpedia.net/translation-books/1947.json",
    "language": { "name": "الإنجليزية", "en_name": "English", "local_name": "English", "code": "en", "direction": "ltr" }
  }
]

Parameters

book_id integer required Translation book ID

surah_id integer required Surah number

ayah_number integer optional Ayah number. Omit for entire surah.

Response

// Single ayah: GET /translation/1947/1/1
{ "ayah_number": 1, "translation_text": "In the name of Allah, the Entirely Merciful, ..." }

// Full surah: GET /translation/1947/1 → returns array of the above

# Surah Info

Parameters

surah_id integer required Surah number (1-114)

Response

{
  "introduction": { "title": "نبذة عن السورة", "value": "..." },
  "surah_number": { "title": "ترتيبها المصحفي", "value": "1" },
  "surah_type": { "title": "نوعها", "value": "مكية" },
  "words_count": { "title": "ألفاظها", "value": "29" },
  "descent": { "title": "ترتيب نزولها", "value": "5" },
  "grace": { "title": "فضلها", "value": "..." },
  "prophet": { "title": "أحاديث عنها", "value": "..." },
  "revelation": { "title": "سبب نزولها", "value": "..." },
  "topics": { "title": "موضوعاتها", "value": "..." },
  "purposes": { "title": "مقاصدها", "value": "..." },
  "asmaoha": { "title": "أسماؤها", "value": "..." },
  "ayahs_count": { "title": "آياتها", "value": "7" }
}

Parameters

surah_id integer required Surah number

Response

[
  {
    "id": 1,
    "name": "تيسير التفسير",
    "short_name": "القطان",
    "author": "إبراهيم القطان"
  }
]

Parameters

surah_id integer required Surah number

Response

[
  {
    "id": 1,
    "ar_title": "لا إثم على من داس على المصحف بغير قصد",
    "question_summary": "دست على المصحف بغير قصد فما حكم ذلك؟...",
    "author": "موقع إسلام ويب"
  }
]

Parameters

surah_id integer required Surah number

Response

[
  {
    "id": 1,
    "name": "تيسير التفسير",
    "short_name": "القطان",
    "author": "إبراهيم القطان"
  }
]

# Topics

Response

[
  { "id": 2951, "name": "الرِّيش", "parent_id": null, "ayahs": "7:26" },
  { "id": 2860, "name": "أسماء الله الحسنى", "parent_id": null, "ayahs": "7:180,17:110,20:8,59:24" }
]

# Reciters

Response

[
  [
    {
      "id": 1,
      "name": "حفص عن عاصم - مرتل",
      "rawi": { "id": 1, "name": "حفص" },
      "recitation_type": { "id": 1, "ar_name": "مرتل" },
      "classification": { "id": 2, "name": "كامل" },
      "surahs_list": [1, 2, 3, "... 1-114"],
      "timing_url": "https://api.quranpedia.net/data/timings/1.zip"
    }
  ]
]

# Categories

Parameters

type string optional "books", "fatwas", or "notes". Adds count per category.

Response

// GET /categories/books
[
  {
    "id": 1,
    "name": "المصاحف",
    "children": [ { "id": 10, "name": "مصاحف مخطوطة", "count": 15 } ],
    "count": 126
  }
]

Parameters

category_id integer required Category ID

type string required "books", "fatwas", or "notes"

Response

// GET /category/2/books
[
  { "id": 1, "name": "تيسير التفسير", "nasher": "", "language": "ar", "author": "إبراهيم القطان" }
]

# Books

Parameters

book_id integer required Book ID

Response

{
  "id": 1,
  "name": "تيسير التفسير",
  "short_name": "القطان",
  "type": "tafsir",
  "language": { "id": 1, "name": "العربية", "code": "ar", "direction": "rtl" },
  "category": { "id": 2, "name": "التفسير", "parent_id": null },
  "parts": 1,
  "publish_year": "1990",
  "edition": "الأولى",
  "nasher": "دار النشر",
  "has_image": false,
  "about": "نبذة عن الكتاب...",
  "author": { "id": 1050, "ar_name": "إبراهيم القطان", "full_name": "إبراهيم القطان" },
  "mohaqeq": null, "introducer": null, "reviewer": null, "translator": null,
  "contents_url": "https://api.quranpedia.net/books-contents/book-1.json",
  "book_attachments": [{ "id": 1, "name": "...", "url": "...", "part": 1 }],
  "relative_ayah_service": "tafsir"
}

Parameters

book_id integer required Book ID

Response

[
  {
    "key": "طبعات أخرى",
    "related_books": [
      { "id": 10, "name": "تيسير التفسير - ط2", "author": "إبراهيم القطان", "publish_year": "1990" }
    ]
  }
]

// Returns empty array [] if no related books exist

# Fatwas

Parameters

fatwa_id integer required Fatwa ID

Response

{
  "id": 1,
  "ar_title": "لا إثم على من داس على المصحف بغير قصد",
  "ar_question": "دست على المصحف بغير قصد فما حكم ذلك؟...",
  "ar_answer": "الحمد لله، والصلاة والسلام على رسول الله...",
  "ar_source_url": "https://www.islamweb.net/ar/fatwa/...",
  "mufti": "موقع إسلام ويب",
  "attachments": [],
  "category": { "id": 55, "name": "غير مصنف" }
}

# Notes

Parameters

note_id integer required Note ID

Response

[
  {
    "note": "...",
    "writer": "اسم الكاتب",
    "ayahs": "1:1,1:2,1:3",
    "attachments": [{ "id": 1, "name": "...", "url": "..." }],
    "category": { "id": 10, "name": "..." },
    "source": { "id": 1, "ar_name": "..." },
    "book": { "id": 5, "name": "...", "short_name": "..." }
  }
]

# Search

Parameters

query string required Search query (URL-encoded)

type string optional "books", "fatwas", "notes", or "topics". Omit for all.

Response

// All types: GET /search/تفسير
{
  "notes":  { "items": [...], "currentPage": 1, "perPage": 15, "total": 42, "lastPage": 3 },
  "fatwas": { "items": [...], "currentPage": 1, "perPage": 15, "total": 18, "lastPage": 2 },
  "topics": { "items": [...], "currentPage": 1, "perPage": 15, "total": 7,  "lastPage": 1 },
  "books":  { "items": [...], "currentPage": 1, "perPage": 15, "total": 31, "lastPage": 3 }
}

// Single type: GET /search/تفسير/books
{
  "items": [
    {
      "book_info": {
        "id": 1, "name": "تيسير التفسير", "category": "التفسير",
        "author": "إبراهيم القطان", "parts": 1, "contents_url": "...",
        "has_image": false, "publish_year": "1990"
      },
      "highlighted_text": "...<em>تفسير</em>..."
    }
  ],
  "currentPage": 1, "perPage": 15, "total": 31, "lastPage": 3
}

# Changes — delta sync

Our content is continuously corrected. Instead of re-downloading, ask what changed since your last sync:

GET /v1/changes?since=2026-08-01

Returns, per content type (ayahs, ayah_book_contents, books, fatwas, notes, topics), the resources corrected since that date — addressed exactly as the API addresses them (mushaf/surah/ayah/book ids), each with a ready refetch path, plus count and truncated (lists cap at 1000 rows). since must be within the last year — for older baselines, start from a fresh dump instead. Quranic-text (ayahs) change tracking begins 2026-08-07.

# Error Responses

When a resource is not found, the API returns a 404 status:

{ "error": "Mushaf not found" }

Invalid parameters return 400:

{ "error": "TYPE NOT FOUND" }

# Usage Examples

JavaScript (fetch)

const BASE = 'https://api.quranpedia.net/v1';

// Get Al-Fatiha from Hafs mushaf
const ayahs = await fetch(`${BASE}/mushafs/1/1`)
  .then(r => r.json());

// Get English translation for ayah 2:255 (Ayat al-Kursi)
const translation = await fetch(`${BASE}/translations/2/255/en`)
  .then(r => r.json());

// Search for books about "تفسير"
const results = await fetch(`${BASE}/search/${encodeURIComponent('تفسير')}/books`)
  .then(r => r.json());

Python (requests)

import requests

BASE = "https://api.quranpedia.net/v1"

# Get all mushafs
mushafs = requests.get(f"{BASE}/mushafs").json()

# Get tafsir for ayah 2:255 from book 1
tafsir = requests.get(f"{BASE}/ayah/2/255/book/1").json()

# Get all reciters
reciters = requests.get(f"{BASE}/reciters").json()

cURL

# Get all topics
curl https://api.quranpedia.net/v1/topics

# Get surah Al-Baqarah info
curl https://api.quranpedia.net/v1/surah/information/2

# Get book details
curl https://api.quranpedia.net/v1/book/1

# Embed Widget & oEmbed

Besides the JSON API, Quranpedia offers a ready-made embeddable widget: a framework-free, stateless page that renders any ayah with its full encyclopedia content (tafsir, word meanings, tadabbur notes, i'rab, qira'at, similar verses, translations, and more) inside an iframe on your site. See the usage guide or the interactive embed builder.

Quick start

<div data-quranpedia-embed data-surah="2" data-ayah="255" data-type="tafsir"></div>
<script src="https://quranpedia.net/embed.js" defer></script>

Key parameters

surah int required Surah number (1–114)

ayah string required Ayah number or range, e.g. 255 or 1-7

type string optional Open a section directly: tafsir, meanings, notes, e3rab, qiraat, similar, topics, fatwa, asbab, nasekh, translations, attachments

theme string optional light (default), dark, or sepia — plus primary/bg/size/radius for full theming

lock bool optional lock=1 pins the widget to the chosen section/book

ayah_text bool optional ayah_text=0 hides the verse card

Full parameter reference in the embed docs.

Parameters

url string required A Quranpedia embed URL or an ayah page URL (/surah/1/{surah}?ayah_id=N)

maxwidth int optional Maximum iframe width (default 600)

maxheight int optional Maximum iframe height (default 500)

Response

{
  "version": "1.0",
  "type": "rich",
  "provider_name": "Quranpedia — الموسوعة القرآنية",
  "title": "سورة البقرة، الآية ٢٥٥ — الموسوعة القرآنية",
  "html": "<iframe src=\"...\" ...></iframe>",
  "width": 600,
  "height": 500
}

# HTML Fragment Endpoints

Server-rendered HTML partials that power the site's live interactions (search-as-you-type, modal content, in-book search). They return HTML, not JSON — useful if you want the same rendered content the site shows. All are plain GET, cacheable, and cookie-free.

fragment bool required fragment=1 returns the content-only partial with data-* metadata on the root

book int optional surah-tafsir: show one tafsir introduction

fatwa int optional surah-fatwa: show one fatwa in full

query string required 2+ characters

type string optional surah, ayah, book, fatwa, note, topic, person, recitation, article, content, tafsir, mushaf, rawi, category