Hosted API access is disabled on `al-quran-database.vercel.app` for now. Use the repository locally or self-host this project to run the API endpoints documented here.

SDK Guide

Complete Quran dataset with TypeScript SDK — works offline with no server. Also includes a REST + GraphQL SDK for self-hosted deployments with all 134 editions.

Install

npm install @faha1999/al-quran-database

Works in browsers, edge runtimes, and Node 18+. ESM-only. Zero runtime dependencies.

Works Offline

Data is bundled in the package. No server, no network call, no .env file needed.

Four editions ship ready for offline use — see Bundled Editions below.

All 134 other editions available via jsDelivr CDN or self-hosted REST API.

Zero-setup quick start

No server. No network. Works immediately.

import { getSurah, getAyah, searchAyahs } from '@faha1999/al-quran-database';

// All of these work with no running server, no network call, no .env file

const fatiha = getSurah(1);
// → { id: 1, name_en: 'Al-Faatiha', ayahs: [...7 resolved ayahs...] }

const withSahih = getSurah(1, 'en.sahih');
// → same, but ayahs include Sahih International translation

const ayah = getAyah(1, 'en.sahih');
// → { text: 'بِسْمِ ٱللَّهِ ...', translation: 'In the name of Allah...' }

const results = searchAyahs('mercy');
// → { items: [...], meta: { total: 50, page: 1, ... } }

Bundled Editions (offline)

Sahih International

en.sahih

English

Yusuf Ali

en.yusufali

English

Simple Arabic (no diacritics)

quran-simple-clean

Arabic

Full Uthmani

quran-uthmani

Arabic

import { BUNDLED_EDITION_IDENTIFIERS } from '@faha1999/al-quran-database';
console.log(BUNDLED_EDITION_IDENTIFIERS);
// → ['en.sahih', 'quran-simple-clean', 'en.yusufali', 'quran-uthmani']

Local Functions (18 offline-ready exports)

getSurah(id, edition?)getAyah(id, edition?)getAyahByNumber(number, edition?)getAllSurahs(page?, limit?)getJuzById(id, edition?)getHizbById(id, edition?)getRubById(id, edition?)getPageById(id, edition?)searchAyahs(query, filters?)getReciters()getDuas(page?, limit?)getKnowledgeByAyah(ayahId)getSurahProfile(id)getKnowledgeFaqs()getResearchReferences()getDatasetMetadata()getAllEditions()getSupportedLanguagesList()

CDN Access via jsDelivr (GitHub)

All data files are served from jsDelivr via the GitHub repository — no extra config, free, global CDN, CORS enabled.

// Base URL format:
// https://cdn.jsdelivr.net/gh/faha1999/al-quran-database@{tag}/{path}

// Surah list (pinned v2.2.0)
https://cdn.jsdelivr.net/gh/faha1999/al-quran-database@v2.2.0/lib/data/surahs.json

// All 6236 ayahs
https://cdn.jsdelivr.net/gh/faha1999/al-quran-database@v2.2.0/lib/data/ayahs.json

// Bundled Sahih translation
https://cdn.jsdelivr.net/gh/faha1999/al-quran-database@v2.2.0/lib/data/ayah-editions/en.sahih.json

// Fetch example:
const res = await fetch('https://cdn.jsdelivr.net/gh/faha1999/al-quran-database@v2.2.0/lib/data/surahs.json');
const surahs = await res.json();

Server SDK — All 134 Editions

For all 134 translations, word-by-word morphology, or real-time search — run the full platform locally or self-hosted.

Local Development

import { QuranDevSDK } from '@faha1999/al-quran-database';

const quran = new QuranDevSDK({
  baseUrl: 'http://localhost:3000',
  apiVersion: 'v1',
});

Self-Hosted API

import { QuranDevSDK } from '@faha1999/al-quran-database';

const quran = new QuranDevSDK({
  baseUrl: 'https://your-domain.example',
});

// Any of 134 editions
const surah = await quran.getSurah(1, 'ur.maududi');

Server SDK Usage

Surah + translation

const surah = await quran.getSurah(1, 'en.sahih');
console.log(surah.name_ar);
console.log(surah.ayahs[0]?.translation);

Ranked search

const { data: results, meta } = await quran.search('mercy', {
  language: 'en',
  limit: 5,
});
console.log(meta.total);
console.log(results[0]?.matched_identifiers);

Ayah with words and knowledge

const ayah = await quran.getAyah(1, 'en.sahih', true);
const knowledge = await quran.getKnowledge(1);

console.log(ayah.words?.[0]?.text);
console.log(knowledge.themes);

GraphQL

const data = await quran.graphql<{
  ayah: { text: string; knowledge: { themes: string[] } | null } | null;
}>({
  query: `
    query GetAyah($id: Int!) {
      ayah(id: $id) {
        text
        knowledge { themes }
      }
    }
  `,
  variables: { id: 1 },
});

QuranDevSDK Methods

getSurahs(page?, limit?)getSurah(id, edition?)getAyah(id, edition?, includeWords?)search(query, { edition?, language?, page?, limit? })getJuz(id, edition?)getHizb(id, edition?)getRub(id, edition?)getPage(id, edition?)getWords(ayahId)getDuas(page?, limit?)getReciters()getFaqs()getKnowledge(ayahId)getMeta()getResearchReferences()graphql({ query, variables? })

Public Exports

`getSurah`, `getAyah`, `searchAyahs` + 15 more local functions

`surahs`, `ayahs`, `editions`, `juzs` + all raw data arrays

`BUNDLED_EDITION_IDENTIFIERS`, `DEFAULT_TRANSLATION_IDENTIFIER`

`QuranDevSDK` class (server-based SDK)

`quran` singleton instance

`QuranApiOptions`, `GraphqlRequest`, `MetaPayload`

All TypeScript entity and response types

Error Handling

// Local functions return null for not-found (no throws):
const surah = getSurah(999); // → null
const ayah = getAyah(99999); // → null

// Server SDK throws on errors:
try {
  await quran.getSurah(999999);
} catch (error) {
  // "Quran API error: 404 Not Found" or envelope error text
}

try {
  await quran.graphql({ query: 'query { nope }' });
} catch (error) {
  // First error message from GraphQL response
}

Defaults

Local functions work with zero config — data is bundled in the package.

QuranDevSDK baseUrl defaults to '' (same-origin).

apiVersion defaults to v1.

Package is ESM-only, targets Node.js 18+.

REST helpers throw on non-2xx responses or failed API envelopes.

GraphQL helper throws on HTTP failures or errors in response.