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​
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],
});