Official Node.js SDK for EQuran.id API v2. Access Quran data including Surahs, Ayat (verses), Tafsir (interpretation), and Audio recitations.
- 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
npm install equranimport { 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);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 namenamaLatin- Latin/transliterated namejumlahAyat- Number of versestempatTurun- Place of revelation ("Mekah" or "Madinah")arti- Meaning/translation of the surah namedeskripsi- Description of the surahaudioFull- Object containing full audio URLs for each Qari
Returns complete surah data including all verses.
| Parameter | Type | Description |
|---|---|---|
nomor |
number |
Surah number (1-114) |
const surah = await quran.getSurat(36);
// Returns: SuratDetailResponse fields:
- All fields from
getAllSurat() ayat- Array of verses (see Ayat structure below)suratSelanjutnya- Next surah reference orfalsesuratSebelumnya- Previous surah reference orfalse
Ayat structure:
nomorAyat- Verse numberteksArab- Arabic textteksLatin- Latin/transliterated textteksIndonesia- Indonesian translationaudio- Object containing audio URLs for each Qari
Returns tafsir (interpretation) for a surah.
| Parameter | Type | Description |
|---|---|---|
nomor |
number |
Surah number (1-114) |
const tafsir = await quran.getTafsir(1);
// Returns: TafsirDetailResponse fields:
- Surah metadata (same as
getAllSurat()) tafsir- Array of tafsir entries for each verseayat- Verse numberteks- Tafsir text
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);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[]
// }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); // 36Returns null if not found.
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)Returns all Makkiyah surahs (revealed in Mecca).
const makkiyah = await quran.getMakkiyahSurat();
// Returns 86 surahsReturns all Madaniyah surahs (revealed in Medina).
const madaniyah = await quran.getMadaniyahSurat();
// Returns 28 surahsReturns 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"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 SudaisReturns 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 |
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);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
// }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); // 83Returns 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).
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).
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);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[]Clears all cached data.
quran.clearCache();Returns cache statistics.
const stats = quran.getCacheStats();
// {
// hits: 10,
// misses: 5,
// size: 5,
// hitRate: 0.667
// }Removes expired cache entries.
const removed = quran.pruneCache();
console.log(`Removed ${removed} expired entries`);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)
}
});All types are exported and available for use:
import type {
Surat,
SuratDetail,
Ayat,
TafsirDetail,
TafsirAyat,
QariInfo,
RandomAyat,
AyatRange,
SuratWithTafsir,
EQuranConfig,
CacheStats,
AudioMap,
} from 'equran';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}`);
}
}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'],
};
}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`);
}
}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`);
}
}- Node.js >= 18.0.0
MIT
- Website: https://equran.id
- API Documentation: https://equran.id/apidev
- GitHub: https://github.com/equran/equran

