Resources Tools Docs FAQ CMS

Juz

Juz info

The Quran is divided into 30 equal parts called Juz to make it easier to recite or memorize in 30 days, especially during Ramadan. Each Juz may span multiple surahs and is based on length, not theme.

Tags

Quran Metadata Juz

Download Links

Download json Download sqlite

About juz metadata

Juz data is exported in both JSON and SQLite formats.

Sample JSON

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

JSON
{
  "1": {
    "juz_number": 1,
    "verses_count": 148,
    "first_verse_key": "1:1",
    "last_verse_key": "2:141",
    "verse_mapping": {
      "1": "1-7",
      "2": "1-141"
    }
  }
}

Field descriptions

Field Type Description
juz_number INTEGER The juz number (1 to 30).
verses_count INTEGER Total number of verses in the juz.
first_verse_key TEXT The key of the first verse in the juz (e.g. 1:1).
last_verse_key TEXT The key of the last verse in the juz (e.g. 2:141).
verse_mapping OBJECT A mapping of surah numbers to ayah ranges within this juz. For example, "2": "1-141" means Surah 2 contributes ayahs 1 to 141 to this juz.

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 juz_number as a string ("1" to "30"). The SQLite file has the same fields in the juz 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 juz. Use them as verse_key values in the other QUL resources.
  • Expand verse_mapping. verse_mapping lists the ayahs of this juz 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.
JavaScript
// Setup: unzip the download and serve quran-metadata-juz.json from your app (here at /data/)
const items = await fetch('/data/quran-metadata-juz.json').then((res) => res.json());

// Get the first juz
const first = items['1']; // { juz_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
SQL
-- SQLite: verse_mapping is JSON text. Parse it in your app.
SELECT juz_number, first_verse_key, last_verse_key, verse_mapping
FROM juz
ORDER BY juz_number;

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