Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Appearance settings
View equran's full-sized avatar

Block or report equran

Block user

Prevent this user from interacting with your repositories and sending you notifications. Learn more about blocking users.

You must be logged in to block users.

Maximum 250 characters. Please don't include any personal information such as legal names or email addresses. Markdown supported. This note will be visible to only you.
Report abuse

Contact GitHub support about this user’s behavior. Learn more about reporting abuse.

Report abuse
equran/README.md

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

Popular repositories Loading

  1. jadwal-imsakiyah-2025 jadwal-imsakiyah-2025 Public

    TypeScript 1

  2. umami umami Public

    Forked from umami-software/umami

    Umami is a modern, privacy-focused alternative to Google Analytics.

    TypeScript

  3. equran equran Public

    Official Node.js SDK for EQuran.id API - Access Quran, Tafsir, and Audio

    TypeScript

Morty Proxy This is a proxified and sanitized view of the page, visit original site.