EQuran

Official Node.js SDK for EQuran.id API v2. Access Quran data including Surahs, Ayat (verses), Tafsir (interpretation), and Audio recitations.

Features

• Complete Data - All 114 Surahs with 6,236 Ayat
• Indonesian Translation - Full Indonesian translation for every verse
• Tafsir - Detailed interpretation for each verse
• Audio Recitations - 6 renowned Qari (reciters)
• Built-in Caching - In-memory cache with TTL support
• TypeScript - Full type definitions included
• Dual Format - Supports both ESM and CommonJS

Installation

npm install equran

Quick Start

import { EQuran } from 'equran';

const quran = new EQuran();

// Get all surahs
const surahs = await quran.getAllSurat();

// Get a specific surah with all verses
const alFatihah = await quran.getSurat(1);

// Get tafsir
const tafsir = await quran.getTafsir(1);

API Reference

Core Functions

getAllSurat()

Returns a list of all 114 surahs with basic information.

const surahs = await quran.getAllSurat();
// Returns: Surat[]

Response fields:

• nomor - Surah number (1-114)
• nama - Arabic name
• namaLatin - Latin/transliterated name
• jumlahAyat - Number of verses
• tempatTurun - Place of revelation ("Mekah" or "Madinah")
• arti - Meaning/translation of the surah name
• deskripsi - Description of the surah
• audioFull - Object containing full audio URLs for each Qari

getSurat(nomor)

Returns complete surah data including all verses.

| Parameter | Type | Description | |-----------|------|-------------| | nomor | number | Surah number (1-114) |

const surah = await quran.getSurat(36);
// Returns: SuratDetail

Response fields:

• All fields from getAllSurat()
• ayat - Array of verses (see Ayat structure below)
• suratSelanjutnya - Next surah reference or false
• suratSebelumnya - Previous surah reference or false

Ayat structure:

• nomorAyat - Verse number
• teksArab - Arabic text
• teksLatin - Latin/transliterated text
• teksIndonesia - Indonesian translation
• audio - Object containing audio URLs for each Qari

getTafsir(nomor)

Returns tafsir (interpretation) for a surah.

| Parameter | Type | Description | |-----------|------|-------------| | nomor | number | Surah number (1-114) |

const tafsir = await quran.getTafsir(1);
// Returns: TafsirDetail

Response fields:

• Surah metadata (same as getAllSurat())
• tafsir - Array of tafsir entries for each verse
  • ayat - Verse number
  • teks - Tafsir text

Helper Functions

getAyat(suratNomor, ayatNomor)

Returns a single verse from a surah.

| Parameter | Type | Description | |-----------|------|-------------| | suratNomor | number | Surah number (1-114) | | ayatNomor | number | Verse number |

const ayatKursi = await quran.getAyat(2, 255);
console.log(ayatKursi.teksArab);
console.log(ayatKursi.teksIndonesia);

getAyatRange(suratNomor, from, to)

Returns a range of verses from a surah.

| Parameter | Type | Description | |-----------|------|-------------| | suratNomor | number | Surah number (1-114) | | from | number | Starting verse number | | to | number | Ending verse number |

const range = await quran.getAyatRange(2, 1, 5);
// Returns: AyatRange
// {
//   suratNomor: 2,
//   suratNama: "البقرة",
//   suratNamaLatin: "Al-Baqarah",
//   fromAyat: 1,
//   toAyat: 5,
//   ayat: Ayat[]
// }

getSuratByName(name)

Finds a surah by its Latin name. Case-insensitive search.

| Parameter | Type | Description | |-----------|------|-------------| | name | string | Latin name to search |

const surah = await quran.getSuratByName('Yasin');
console.log(surah?.nomor); // 36

Returns null if not found.

searchSurat(keyword)

Searches surahs by keyword. Searches in Arabic name, Latin name, and meaning.

| Parameter | Type | Description | |-----------|------|-------------| | keyword | string | Search keyword |

const results = await quran.searchSurat('sapi');
// Returns Al-Baqarah (meaning: The Cow/Sapi)

getMakkiyahSurat()

Returns all Makkiyah surahs (revealed in Mecca).

const makkiyah = await quran.getMakkiyahSurat();
// Returns 86 surahs

getMadaniyahSurat()

Returns all Madaniyah surahs (revealed in Medina).

const madaniyah = await quran.getMadaniyahSurat();
// Returns 28 surahs

Audio Functions

getAudioFull(suratNomor, qariId?)

Returns the full surah audio URL.

| Parameter | Type | Description | |-----------|------|-------------| | suratNomor | number | Surah number (1-114) | | qariId | string | Optional. Qari ID (default: "05") |

const audioUrl = await quran.getAudioFull(36, '05');
// "https://cdn.equran.id/audio-full/Misyari-Rasyid-Al-Afasi/036.mp3"

getAudioAyat(suratNomor, ayatNomor, qariId?)

Returns the audio URL for a specific verse.

| Parameter | Type | Description | |-----------|------|-------------| | suratNomor | number | Surah number (1-114) | | ayatNomor | number | Verse number | | qariId | string | Optional. Qari ID (default: "05") |

const audioUrl = await quran.getAudioAyat(2, 255, '03');
// Returns Ayat Kursi audio by Sudais

getQariList()

Returns the list of available Qari (reciters).

const qariList = quran.getQariList();

Available Qari:

| ID | Name | |----|------| | 01 | Abdullah Al-Juhany | | 02 | Abdul Muhsin Al-Qasim | | 03 | Abdurrahman as-Sudais | | 04 | Ibrahim Al-Dossari | | 05 | Misyari Rasyid Al-Afasi (default) | | 06 | Yasser Al-Dosari |

Utility Functions

getTafsirAyat(suratNomor, ayatNomor)

Returns tafsir for a specific verse.

| Parameter | Type | Description | |-----------|------|-------------| | suratNomor | number | Surah number (1-114) | | ayatNomor | number | Verse number |

const tafsir = await quran.getTafsirAyat(1, 1);
console.log(tafsir.teks);

getRandomAyat()

Returns a random verse from the Quran with surah context.

const random = await quran.getRandomAyat();
// Returns: RandomAyat
// {
//   suratNomor: 36,
//   suratNama: "يس",
//   suratNamaLatin: "Ya-Sin",
//   ayat: Ayat
// }

getSuratInfo(nomor)

Returns surah information without verses. Lighter response for list/preview purposes.

| Parameter | Type | Description | |-----------|------|-------------| | nomor | number | Surah number (1-114) |

const info = await quran.getSuratInfo(36);
console.log(info.jumlahAyat); // 83

getNextSurat(currentNomor)

Returns the next surah.

| Parameter | Type | Description | |-----------|------|-------------| | currentNomor | number | Current surah number (1-113) |

const next = await quran.getNextSurat(1);
console.log(next?.namaLatin); // "Al-Baqarah"

Returns null if current surah is 114 (An-Nas).

getPrevSurat(currentNomor)

Returns the previous surah.

| Parameter | Type | Description | |-----------|------|-------------| | currentNomor | number | Current surah number (2-114) |

const prev = await quran.getPrevSurat(2);
console.log(prev?.namaLatin); // "Al-Fatihah"

Returns null if current surah is 1 (Al-Fatihah).

Advanced Functions

getSuratWithTafsir(nomor)

Returns both surah data and tafsir in a single call. Uses parallel requests for efficiency.

| Parameter | Type | Description | |-----------|------|-------------| | nomor | number | Surah number (1-114) |

const { surat, tafsir } = await quran.getSuratWithTafsir(1);

bulkGetSurat(nomorList)

Fetches multiple surahs in parallel.

| Parameter | Type | Description | |-----------|------|-------------| | nomorList | number[] | Array of surah numbers |

const surahs = await quran.bulkGetSurat([1, 36, 67, 78]);
// Returns: SuratDetail[]

Cache Management

clearCache()

Clears all cached data.

quran.clearCache();

getCacheStats()

Returns cache statistics.

const stats = quran.getCacheStats();
// {
//   hits: 10,
//   misses: 5,
//   size: 5,
//   hitRate: 0.667
// }

pruneCache()

Removes expired cache entries.

const removed = quran.pruneCache();
console.log(`Removed ${removed} expired entries`);

Configuration

const quran = new EQuran({
  // Base API URL (default: https://equran.id/api/v2)
  baseUrl: 'https://equran.id/api/v2',
  
  // Request timeout in milliseconds (default: 30000)
  timeout: 30000,
  
  // Cache configuration
  cache: {
    enabled: true,         // Enable caching (default: true)
    ttl: 60 * 60 * 1000,   // TTL in ms (default: 1 hour)
    maxSize: 200,          // Max cache entries (default: 200)
  }
});

TypeScript

All types are exported and available for use:

import type {
  Surat,
  SuratDetail,
  Ayat,
  TafsirDetail,
  TafsirAyat,
  QariInfo,
  RandomAyat,
  AyatRange,
  SuratWithTafsir,
  EQuranConfig,
  CacheStats,
  AudioMap,
} from 'equran';

Error Handling

import { EQuran, EQuranApiError } from 'equran';

try {
  const surah = await quran.getSurat(999);
} catch (error) {
  if (error instanceof EQuranApiError) {
    console.error(`API Error: ${error.message}`);
    console.error(`Status Code: ${error.statusCode}`);
    console.error(`Endpoint: ${error.endpoint}`);
  }
}

Examples

Daily Verse Widget

async function getDailyVerse() {
  const quran = new EQuran();
  const random = await quran.getRandomAyat();
  
  return {
    surah: random.suratNamaLatin,
    verse: random.ayat.nomorAyat,
    arabic: random.ayat.teksArab,
    translation: random.ayat.teksIndonesia,
    audio: random.ayat.audio['05'],
  };
}

Quran Reader

async function readSurah(nomor: number) {
  const quran = new EQuran();
  const surah = await quran.getSurat(nomor);
  
  console.log(`${surah.namaLatin} (${surah.nama})`);
  console.log(`${surah.tempatTurun} | ${surah.jumlahAyat} verses`);
  console.log(`Meaning: ${surah.arti}\n`);
  
  for (const ayat of surah.ayat) {
    console.log(`[${ayat.nomorAyat}] ${ayat.teksArab}`);
    console.log(`    ${ayat.teksIndonesia}\n`);
  }
}

Surah with Tafsir

async function studySurah(nomor: number) {
  const quran = new EQuran();
  const { surat, tafsir } = await quran.getSuratWithTafsir(nomor);
  
  for (let i = 0; i < surat.ayat.length; i++) {
    const ayat = surat.ayat[i];
    const tafsirAyat = tafsir.tafsir[i];
    
    console.log(`--- Verse ${ayat.nomorAyat} ---`);
    console.log(`Arabic: ${ayat.teksArab}`);
    console.log(`Translation: ${ayat.teksIndonesia}`);
    console.log(`Tafsir: ${tafsirAyat.teks}\n`);
  }
}

Requirements

• Node.js >= 18.0.0

License

MIT

Links

• Website: https://equran.id
• API Documentation: https://equran.id/apidev
• GitHub: https://github.com/equran/equran