quran-json turns the Quran into static files with open CORS and a manifest

Static files instead of an API

quran-json is the Quran as static JSON files: Arabic text in 15 scripts, 130 translations in 81 languages, 3 transliterations, and links to per-ayah recitations. The README puts the design in one line: no API key and no server code, you fetch a file.

That is a deliberate architectural choice, and it changes what the project is good for. Any static host, any CDN, any object store can serve these files, and a client can fetch them with the same code it uses to fetch a JavaScript bundle. There is no key to leak, no rate limit to design around and no availability dependency beyond the host you choose.

The first request is a chapter:

curl -s https://quran-json.risanb.com/text/uthmani/chapters/1.json

and every file is served with `Access-Control-Allow-Origin: *`, so a browser application can read it cross-origin without a proxy. There is also a reader at the documentation site and a set of docs, and the data lives in the repository rather than only on the server.

The audience is therefore application developers. Someone building a Quran reader, a search tool, a study app or a language learning product wants structured text with stable identifiers, and this provides exactly that, with the provenance recorded alongside it.

The endpoint map and joining on the verse id

The endpoint table is the API, and it is worth reading in full because it explains the shape of the data.

/manifest.json holds scripts, counts, licences and attribution. /chapters.json holds the 114 chapters with names, meaning, type and verse count. /text/{script}/quran.json is one script for all chapters, and /text/{script}/chapters/{1-114}.json is one script for one chapter, shaped as an object with an id and a verses array whose entries carry an id and text. The translations and transliteration trees follow the same pattern, each with an index file listing the available editions with their language, translator, version and licence.

Two meta endpoints do work that most datasets skip. /meta/sources.json records the source, licence and checksum of every snapshot, and /meta/qa.json lists corrections applied to upstream text with the evidence for them.

The joining model is the detail that matters for an application. A file for a chapter is an array of verses with numeric ids, and a translation file for the same chapter has the same ids, so you align them by index:

const base = "https://quran-json.risanb.com";
const [arabic, english] = await Promise.all([
  fetch(`${base}/text/uthmani/chapters/2.json`).then((r) => r.json()),
  fetch(`${base}/translations/en-saheeh/chapters/2.json`).then((r) => r.json()),
]);
// Join on the verse id: arabic.verses[254] and english.verses[254] are both 2:255.

The comment is the contract. Because translations, transliterations and per-ayah audio all use Hafs verse numbers, one index works across the text, the translation and the audio link, with no mapping table in your code.

Choosing a script, and the verse numbering trap

The script section exists because the right choice depends on your use and your users.

For most applications, in the Madinah mushaf and the Hafs reading, the answer is uthmani, and for KFGQPC fonts it is qpc-hafs. For search and matching, simple-clean has no vowel marks. For South Asia there are two, hafs-nastaliq in KFGQPC Nastaleeq and indopak in DigitalKhatt. Indonesia has kemenag, the Mushaf Standar Indonesia. North and West Africa use warsh for Morocco, Algeria and West Africa, or qalun for Libya and Tunisia, and Sudan uses duri. Other variants are published too, uthmani-min, simple, simple-min, simple-plain as Tanzil variants, plus the two readings mostly used by specialists, shubah and susi.

Two cautions follow, and both are the kind of thing that quietly corrupts an application.

The first is that a script is a text, not a page layout. 13, 15 and 16-line mushafs differ in line breaks, and a verse array does not carry line breaks. If your product is a page facsimile, this dataset is the wrong shape.

The second is verse numbering. Hafs scripts have 6,236 verses. Warsh, Qalun, al-Duri and al-Susi number their verses differently, so each of their verses carries number_in_hafs, the Hafs verse number or numbers it covers. The manifest's verse_ids, reading and bismillah fields say how each script behaves, and they are the fields to check before you index anything.

Translations, their licences, and the withheld list

There are 130 editions in 81 languages, and the README is precise about where each comes from and what it permits.

118 of them come from QuranEnc, which permits republishing verbatim with credit and version, and both of those are recorded in the translations index. ClearQuran by Talal Itani is included in two editions, one using God and one using Allah, under CC BY-ND 4.0, which is a no-derivatives licence and therefore a different deal from the rest. A group of editions are in the public domain: Sale, Rodwell, Palmer, Pickthall and Yusuf Ali in English, Sablukov and Krachkovsky in Russian, Ahmed Raza Khan and Mahmud ul Hasan in Urdu, and Keyzer in Dutch.

The interesting detail is the last one. Editions that are incomplete upstream are listed under `withheld`, with the reason.

That is the part to notice. A dataset that silently omitted a half-finished translation would look identical to one that had it, and a reader would assume a gap in the data rather than a decision by the publisher. Listing withheld editions with their reasons means the gap is documented, and the translations index still records the language, translator, version and licence for the editions that are there.

For a product, the practical consequence is that your licence review is per edition, not per language, and the index file is the document to diff against your requirements.

The transliterations are machine generated and not reviewed

The transliteration section is the one place where the README is blunt about a limitation, and it is worth quoting the shape of it.

Three transliterations are generated by this project from the Kemenag Arabic text: id-skb in Indonesian, SKB 1987 style, en in English with diacritics, and en-simple in plain English. They follow Hafs connected-reading rules, which means sun letters, joining at hamzat al-wasl, idgham, iqlab and pause forms are all handled.

The validation is reported in detail. The Indonesian output matches Kemenag's own romanisation in 87% of verses, compared after removing spaces, punctuation and case, with the comparison in romanize_validation.py, and the README attributes most of the remaining differences to style or to typos in the reference.

And then the sentence that decides whether you can ship it: the transliterations are machine-generated and not yet reviewed by a qualified reader.

That is a narrow, honest caveat, and it is placed exactly where a reader will see it. A Latin transliteration is not a neutral rendering, because a project has to decide how to represent sounds that the Latin alphabet does not carry, and those decisions are the kind that a native reader and a scholar will each want to check. For a study tool where accuracy is the product, this data is not ready without that review. For a search index or a matching feature, it is a reasonable starting point.

The generated output is also not a static file, which matters for the build story later.

Audio is linked rather than hosted, and the licences do not all match

The audio section is short. Audio is linked, not hosted. The reciters file lists 597 recordings from EveryAyah, Islamic Network and MP3Quran as URL templates, for example:

https://everyayah.com/data/Alafasy_128kbps/{surah:03d}{ayah:03d}.mp3

Each recording states its reading, and per-ayah files use Hafs numbering, so they can only be used with a Hafs script. That is the same constraint as the verse numbering, and it means the audio, the text and the translations all line up only if you have chosen the right script.

The licence table is where the project's care shows. Tanzil is used for 6 Tanzil scripts and the chapter metadata under CC BY 3.0, verbatim only, and its notice is in every chapter file. Quranpedia.net provides the KFGQPC editions, with the terms of republishing with credit and the dump version. Qur'an Kemenag provides the kemenag script, where the README notes there is no copyright on the mushaf text under PMA 44/2016, Pasal 8. DigitalKhatt provides indopak under MIT. This project covers the transliterations under CC BY-SA 4.0. And the audio is linked only, with EveryAyah and MP3Quran stating no licence.

There is also a duty that is not a copyright question. In Indonesia, any medium that holds the Quran text needs an LPMQ tashih under PMA 44/2016, which is a separate duty from copyright.

For an English-language application the practical rule is simple: use a public domain or CC BY-ND translation with its credit line, take the text from Tanzil or the KLQPC editions with their notices, and treat the audio as links to somebody else's server.

Building the data, and the rules for changing it

The dataset is a build product, and the repository shows the pipeline.

Development requires uv and Node.js 22.12 or newer, and the commands are:

uv sync                        # Python dependencies
npm ci --prefix site           # site dependencies
uv run pytest                  # data tests
npm run site -- --no-cdn       # build data + site into .build/assembled
npm run dev --prefix site      # site dev server (after one build)

The CLI itself is a Typer application exposed as the quran-json command. `uv run quran-json fetch` downloads upstream snapshots into the data directory, with --force to refresh, and `fetch --check` compares upstream with the committed data and exits 1 on any change, which is the check that runs in CI. `verify` checks snapshot hashes and licences, `cdn --out DIR` generates the JSON tree, `crosscheck` compares the texts with independent copies over the network, and `probe` checks a sample of audio URLs.

The important property is that builds read only the committed snapshots in data/, so they work offline. The site is Astro, React, Tailwind and shadcn/ui, and Cloudflare Workers serves the cdn/ directory that the site build writes. The Python side requires 3.12 or newer, uses hatchling as the build backend, and is checked with ruff and mypy in strict mode.

The changes policy is the part that makes a published dataset safe to depend on. A published path is never renamed or removed. Content can be corrected when an upstream source corrects it, corrections are logged in /meta/qa.json, and source versions are in /meta/sources.json. Data files are cached for one day. And the old npm package, quran-json at version 3.1.2 or below, is deprecated but still served by npm and jsDelivr, with the files remaining at the git tag v3.1.2.

That last point is the difference between a dataset and a moving target. A path that cannot disappear means a bookmarked URL in your application keeps working.

Editorial conclusion

quran-json suits an application that needs Quran text or a translation at runtime, or at build time, without an API key, a quota or a server to run, and its manifest, source and correction records make it far easier to audit than a scraped dataset. It is the wrong choice if you need a mushaf page layout rather than a verse array, if you need a reading whose numbering is not Hafs and cannot map it, or if you need a reviewed transliteration. Verify first which script and translation licence your product has to satisfy, read /meta/sources.json and /meta/qa.json before shipping, and treat the transliterations as unreviewed machine output until someone qualified has read them.

Frequently asked questions

Official sources

1. Issues
2. License: CC-BY-SA-4.0
3. Project website
4. README
5. risan/quran-json on GitHub