Ayah

About ayah metadata

This resource provides metadata about each ayah in the Quran. If you are looking to download a specific ayah by ayah Quranic script, refer to the Quran Script resource instead.

Sample JSON

{
  "1": {
    "id": 1,
    "surah_number": 1,
    "ayah_number": 1,
    "verse_key": "1:1",
    "words_count": 4,
    "text": "بِسۡمِ ٱللَّهِ ٱلرَّحۡمَٰنِ ٱلرَّحِيمِ ١"
  }
}

Field descriptions

How to use this resource

Download the JSON or SQLite file from the download links on this page. The JSON file is one object, not an array: each key is the ayah id as a string ("1" to "6236") and always equals the id field. The SQLite file has the same fields in the verses table.

• Join with other resources. verse_key (surah:ayah, for example 2:255) is the shared reference across QUL. Use it as the lookup key to attach translations, tafsirs, scripts and audio segments to an ayah.
• List the ayahs of a surah. Filter on surah_number and ayah_number. Both are integers, so you can also build ranges.
• Clean the text. text is in the QPC Hafs script. Each ayah ends with its number in Arabic-Indic digits (٠ to ٩), and some ayahs start with the ۞ sign (rubʿ al-ḥizb marker). Remove both before you search or compare text; the code below shows how. For other scripts and fonts, see the Quran Script resources.

// Setup: unzip the download and serve quran-metadata-ayah.json from your app (here at /data/)
const ayahs = await fetch('/data/quran-metadata-ayah.json').then((res) => res.json());

// Get an ayah by id
const first = ayahs['1']; // { id: 1, verse_key: "1:1", words_count: 4, ... }

// Build a lookup by verse_key to join with other QUL resources
const byVerseKey = new Map(Object.values(ayahs).map((ayah) => [ayah.verse_key, ayah]));
byVerseKey.get('1:1').words_count; // 4

// All ayahs of surah 1
const alFatihah = Object.values(ayahs).filter((ayah) => ayah.surah_number === 1); // 7 ayahs

// Remove the leading ۞ sign and the trailing ayah number
const plainText = first.text.replace(/^\u06DE\s*|\s*[\u0660-\u0669]+$/gu, '');

-- SQLite: the same fields are in the verses table
SELECT verse_key, words_count, text
FROM verses
WHERE surah_number = 1
ORDER BY ayah_number;

For a longer walkthrough, see Tutorial 7: Quran Metadata End-to-End.