About ruku metadata

Ruku data is exported in both JSON and SQLite formats.

Sample JSON

Here is an example of the JSON structure for the first Ruku:

{
  "1": {
    "ruku_number": 1,
    "surah_ruku_number": 1,
    "verses_count": 7,
    "first_verse_key": "1:1",
    "last_verse_key": "1:7",
    "verse_mapping": {
      "1": "1-7"
    }
  }
}

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: each key is the ruku_number as a string ("1" to "558"). The SQLite file has the same fields in the ruku table, but verse_mapping is JSON text there. Parse it before you use it.

• Find the start and end. first_verse_key and last_verse_key (surah:ayah) are the first and last ayah of each ruku. Use them as verse_key values in the other QUL resources.
• Expand verse_mapping. verse_mapping lists the ayahs of this ruku in each surah. Each key is a surah number, and each value is a string like "1-141", meaning ayahs 1 to 141, both included. Split it on - and convert both numbers to integers.
• Find the position in the surah. surah_ruku_number restarts at 1 in each surah. ruku_number continues from 1 to 558 across the whole Quran.

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

// Get the first ruku
const first = items['1']; // { ruku_number: 1, first_verse_key: "1:1", verse_mapping: { ... }, ... }

// Expand verse_mapping into a list of verse keys
const verseKeys = Object.entries(first.verse_mapping).flatMap(([surah, range]) => {
  const [from, to] = range.split('-').map(Number);
  return Array.from({ length: to - from + 1 }, (_, i) => `${surah}:${from + i}`);
});
verseKeys.length === first.verses_count; // true

-- SQLite: verse_mapping is JSON text. Parse it in your app.
SELECT ruku_number, first_verse_key, last_verse_key, verse_mapping
FROM ruku
ORDER BY ruku_number;

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