Verses API

The Verses API provides access to Quranic verses with support for translations, tafsirs, audio, and word analysis.

Get Verse by Key

const verse = await client.verses.findByKey("2:255");
const firstVerse = await client.verses.findByKey("1:1");
const lastVerse = await client.verses.findByKey("114:6");

Get Verses by Range

const verses = await client.verses.findByRange("1:1", "1:7");

Verse Type

Field	Type	Notes
id	number	Database identifier for the verse.
verseNumber	number	Verse number within the surah.
verseKey	string	Verse key in chapter:verse format.
chapterId	number \| string	Chapter that contains the verse.
pageNumber	number	Mushaf page containing the verse.
juzNumber	number	Juz where the verse appears.
hizbNumber	number	Hizb number (1–60).
rubElHizbNumber	number	Rub' position within the Hizb.
words	Word[]	Optional word-level metadata.
textUthmani*	string	Various Uthmani scripts (textUthmani, textUthmaniSimple, textUthmaniTajweed).
textImlaei*	string	Imlaei script variants (textImlaei, textImlaeiSimple).
textIndopak*	string	IndoPak script variants (textIndopak, textIndopakNastaleeq).
imageUrl	string	Optional rendered verse image URL.
imageWidth	number	Width for the rendered image.
v1Page	number	Legacy Quran.com v1 page number.
v2Page	number	Legacy Quran.com v2 page number.
codeV1	string	Legacy Uthmani code (deprecated).
codeV2	string	Legacy code for the v2 dataset.
translations	Translation[]	Translations returned with the verse.
tafsirs	Tafsir[]	Tafsir entries returned with the verse.
audio	AudioResponse	Optional audio metadata.

With Translations

const verse = await client.verses.findByKey("2:255", {
  translations: [20, 131], // English and Urdu
  words: true,
  translationFields: {
    languageName: true,
    resourceName: true,
    verseKey: true,
  },
});

With Audio

const verse = await client.verses.findByKey("1:1", {
  reciter: 2,
  words: true,
});

With Tafsir

const verse = await client.verses.findByKey("1:1", {
  tafsirs: [171],
  translations: [20],
});

Get Verses by Chapter

const verses = await client.verses.findByChapter("1");

const paginated = await client.verses.findByChapter("2", {
  translations: [20],
  perPage: 10,
  page: 1,
  words: true,
});

Get Verses by Page

const firstPage = await client.verses.findByPage("1");
const page42 = await client.verses.findByPage("42", {
  translations: [131],
});

Get Verses by Divisions

// By Juz
const juz1 = await client.verses.findByJuz("1");

// By Hizb
const hizb1 = await client.verses.findByHizb("1");

// By Rub
const rub1 = await client.verses.findByRub("1");

Get Random Verse

const random = await client.verses.findRandom({
  translations: [20],
  words: true,
});

Field Selection

Word Fields

const verse = await client.verses.findByKey("1:1", {
  words: true,
  wordFields: {
    textUthmani: true,
    verseKey: true,
    location: true,
  },
});

Translation Fields

const verse = await client.verses.findByKey("2:255", {
  translations: [20, 131],
  translationFields: {
    languageName: true,
    resourceName: true,
    verseKey: true,
  },
});

Verse Fields

const verse = await client.verses.findByKey("1:1", {
  fields: {
    textUthmani: true,
    textUthmaniTajweed: true,
    codeV1: true,
    v1Page: true,
  },
});

Pagination

const verses = await client.verses.findByChapter("2", {
  page: 1,
  perPage: 20,
  translations: [20],
});