al-quran-sdk

# npm
npm install al-quran-sdk
 
# yarn
yarn add al-quran-sdk
 
# pnpm
pnpm add al-quran-sdk
 
# bun
bun add al-quran-sdk

import { chapter, verse, audio } from 'al-quran-sdk';
 
// List all 114 chapters in English
const { chapters } = await chapter.listChapters('en');
 
// Fetch verse 1:1 (Al-Fatiha, ayah 1)
const { verses } = await verse.getSpecificVerseByVerseKey('1:1', {
  translations: '131',         // Sahih International
  fields: 'text_uthmani',
});
 
// Get Mishary Rashid Alafasy reciting Surah Al-Ikhlas
const recitation = await audio.getChaptersAudioOfAReciter(7, 112);
console.log(recitation.audio_url);

const { chapter, verse } = require('al-quran-sdk');
 
chapter.getChapter(1, 'en')
  .then((res) => console.log(res.name_simple)) // "Al-Fatihah"
  .catch(console.error);

import { chapter, verse, quran, juz, audio, resources } from 'al-quran-sdk';

import * as Quran from 'al-quran-sdk';
 
Quran.chapter.listChapters('en');

import type { Chapter, Verse, VerseResponse, IAudio } from 'al-quran-sdk';

chapter.listChapters(language?: string): Promise<ListChapters>
chapter.getChapter(id: number, language?: string): Promise<Chapter>
chapter.getChapterInfo(chapter_id: number, language?: string): Promise<ChapterInfo>

const { chapters } = await chapter.listChapters('en');
// chapters[0] => { id: 1, name_simple: 'Al-Fatihah', verses_count: 7, ... }
 
const surah = await chapter.getChapter(2, 'en');
// surah.name_arabic => "البقرة"
 
const info = await chapter.getChapterInfo(1, 'en');
// info.text => "Al-Fatihah is the opening chapter..."

// Page 1 of the Mushaf with Uthmani text + Sahih International translation
const { verses, pagination } = await verse.getVerseByPage('1', {
  language: 'en',
  words: 'true',
  translations: '131',
  fields: 'text_uthmani',
});
 
// A random ayah, with Bengali translation
const random = await verse.getRandomAyah({
  language: 'bn',
  translations: '161',
});

// Script variants
quran.getUthmaniScriptOfAyah(query?)         // Uthmani
quran.getUthmaniSimpleScriptOfAyah(query?)   // Uthmani (simple)
quran.getUthmaniTajweedScriptOfAyah(query?)  // Uthmani with tajweed colour markup
quran.getIndoPakScriptOfAyah(query?)         // Indo-Pak style
quran.getImlaeiSimpleTextOfAyah(query?)      // Imlaei (modern Arabic spelling)
 
// Glyph codes (for QPC Hafs font rendering)
quran.getGlyphCodesOfAyahV1(query?)
quran.getGlyphCodesOfAyahV2(query?)
 
// Single translation / tafsir
quran.getASingleTranslation(translation_id: string, query?: TranslationQuery)
quran.getSingleTafsir(tafsir_id: string, query?: TranslationQuery)

const { verses } = await quran.getUthmaniScriptOfAyah({ chapter_number: '112' });
// verses[0].text_uthmani => "قُلْ هُوَ ٱللَّهُ أَحَدٌ"
 
// Sahih International (131) for Surah Al-Ikhlas
const translation = await quran.getASingleTranslation('131', {
  chapter_number: '112',
});

juz.getAllJuzs(): Promise<JuzResponse>

const { juzs } = await juz.getAllJuzs();

// Whole-chapter recitations
audio.getChaptersAudioOfAReciter(reciter_id, chapter_number) // one chapter
audio.getAllChaptersAudioOfAReciter(reciter_id)              // all 114
audio.getListOfChapterReciters(language?)                    // reciter directory
 
// Ayah-level recitations
audio.getRecitations(language?)                                   // recitation list
audio.getAllAudioFilesofARecitation(recitation_id, query?)        // bulk audio
audio.getAyahRecitationsForSpecificSurah(recitation_id, chapter)  // by surah
audio.getAyahRecitationsForSpecificJuz(recitation_id, juz)        // by juz
audio.getAyahRecitationForSpecificMadaniMushafPage(rid, page)     // by page
audio.getAyahRecitationForSpecificRubelHizb(rid, rub)             // by rub
audio.getAyahRecitationForSpecificHizb(rid, hizb)                 // by hizb
audio.getAyahRecitationForSpecificAyah(rid, ayah_key)             // by ayah

// Mishary Rashid Alafasy (id 7) reciting Surah Yasin (36)
const { audio_url } = await audio.getChaptersAudioOfAReciter(7, 36);
 
// All ayah-level audio files for recitation 7 in Surah Al-Fatiha
const { audio_files, pagination } = await audio.getAyahRecitationsForSpecificSurah(7, 1);
audio_files.forEach((file) => console.log(file.url, file.duration));

resources.getTranslations(language?)            // translation directory
resources.getTranslationInfo(translation_id)    // single translation metadata
resources.getTafsirs(language?)                 // tafsir directory
resources.getTafsirInfo(tafsir_id)              // single tafsir metadata
resources.getRecitationInfo(recitation_id)      // reciter biography
resources.getRecitationStyles()                 // mujawwad / murattal / muallim
resources.getLanguages()                        // every supported language
resources.getChapterInfos()                     // all chapter descriptions
resources.getVerseMedias()                      // verse media listing

const { translations } = await resources.getTranslations('en');
// pick the resource_id you want, then feed it to verse.* or quran.*

en, ur, bn, tr, es, fr, bs, ru, ml, id, uz, nl, de, tg, ta, ja, it, vi, zh,
sq, fa, bg, bm, ha, pt, ro, hi, sw, kk, th, tl, km, as, ko, so, az, ku, dv,
ms, prs, zgh, am, ce, cs, fi, gu, he, ka, kn, ks, lg, mk, mr, mrn, ne, no,
om, pl, ps, rw, sd, se, si, sr, sv, te, tt, ug, uk, yo

import { audio, AudioError, LanguageValidationError } from 'al-quran-sdk';
 
try {
  await audio.getChaptersAudioOfAReciter(7, 36);
} catch (err) {
  if (err instanceof AudioError) {
    // missing reciter id or chapter number
  } else if (err instanceof LanguageValidationError) {
    // bad language code
  } else {
    // network / HTTP error from axios
  }
}

import type {
  Chapter,
  ListChapters,
  ChapterInfo,
  Verse,
  VerseResponse,
  VerseQuery,
  QuranQuery,
  IAudio,
  IRecitation,
  IReciters,
  ISingleRecitation,
  IAyahRecitationSpecificSurah,
  TranslationResponse,
  TafsirsResponse,
  LanguageResponse,
  // ...and many more
} from 'al-quran-sdk';