Skip to main content

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");

Verse Type​

FieldTypeNotes
idnumberDatabase identifier for the verse.
verseNumbernumberVerse number within the surah.
verseKeystringVerse key in chapter:verse format.
chapterIdnumber \| stringChapter that contains the verse.
pageNumbernumberMushaf page containing the verse.
juzNumbernumberJuz where the verse appears.
hizbNumbernumberHizb number (1–60).
rubElHizbNumbernumberRub' position within the Hizb.
wordsWord[]Optional word-level metadata.
textUthmani*stringVarious Uthmani scripts (textUthmani, textUthmaniSimple, textUthmaniTajweed).
textImlaei*stringImlaei script variants (textImlaei, textImlaeiSimple).
textIndopak*stringIndoPak script variants (textIndopak, textIndopakNastaleeq).
imageUrlstringOptional rendered verse image URL.
imageWidthnumberWidth for the rendered image.
v1PagenumberLegacy Quran.com v1 page number.
v2PagenumberLegacy Quran.com v2 page number.
codeV1stringLegacy Uthmani code (deprecated).
codeV2stringLegacy code for the v2 dataset.
translationsTranslation[]Translations returned with the verse.
tafsirsTafsir[]Tafsir entries returned with the verse.
audioAudioResponseOptional 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],
});