Express Quran API

A fast and efficient Express.js API for serving Quran data with multi-language translation support, built-in caching, and optimized search functionality.

Features

• Multi-language Support: Arabic text with translations in multiple languages
• Fast Search: Optimized search with indexing for Arabic text and translation search
• Caching System: Built-in memory caching for improved performance
• Filtering: Filter surahs by type (Meccan/Medinan)
• Random Ayah: Get random verses with translations
• TypeScript Support: Full TypeScript definitions included

Installation

npm install express-quran-api

Quick Start

const ExpressQuranAPI = require('express-quran-api');

const api = new ExpressQuranAPI({
  port: 4000,
  extraLanguages: ['ur', 'fr', 'es', 'tr', 'en']
});

api.listen();

Configuration

Constructor Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | port | number | 3000 | Server port | | dataPath | string | ./data | Path to JSON data files | | extraLanguages | string[] | [] | Additional language codes to load |

Data Files Structure

Place your JSON files in the data directory:

• quran_ar.json (required) - Arabic Quran data
• quran_en.json (optional) - English translation
• quran_ur.json (optional) - Urdu translation
• etc.

API Endpoints

Get All Surahs

GET /api/surahs

Filter Surahs by Type

GET /api/surahs?filterType=true&type=meccan
GET /api/surahs?filterType=true&type=medinan

Search

GET /api/search?q=الله
GET /api/search?q=Allah&lang=en
GET /api/search?q=خدا&lang=ur

Random Ayah

GET /api/random
GET /api/random?lang=en
GET /api/random?lang=ur

Response Examples

Surahs Response

[
  {
    "id": 1,
    "name": "الفاتحة",
    "type": "meccan",
    "translationName": {
      "en": "The Opening",
      "ur": "فاتحہ"
    },
    "verses": [
      {
        "id": 1,
        "text": "بِسْمِ اللَّهِ الرَّحْمَٰنِ الرَّحِيمِ",
        "translation": {
          "en": "In the name of Allah, the Beneficent, the Merciful",
          "ur": "اللہ کے نام سے جو رحمان و رحیم ہے"
        }
      }
    ]
  }
]

Search Response

[
  {
    "surah": 1,
    "surahName": "الفاتحة",
    "surahTranslation": "The Opening",
    "ayah": 1,
    "text": "بِسْمِ اللَّهِ الرَّحْمَٰنِ الرَّحِيمِ",
    "translation": "In the name of Allah, the Beneficent, the Merciful"
  }
]

Random Ayah Response

{
  "surah": 2,
  "surahName": "البقرة",
  "ayah": 255,
  "text": "اللَّهُ لَا إِلَٰهَ إِلَّا هُوَ الْحَيُّ الْقَيُّومُ",
  "translation": "Allah - there is no deity except Him, the Ever-Living, the Sustainer of existence"
}

Performance Features

• Memory Caching: Frequently requested data is cached in memory
• Search Indexing: Arabic text is pre-indexed for faster word-based searches
• Optimized JSON Parsing: Data is loaded once at startup
• Request Optimization: Minimal response payload size

Supported Languages

The API supports any language code you provide. Common examples:

• ar - Arabic (default)
• en - English
• ur - Urdu
• fr - French
• es - Spanish
• tr - Turkish

TypeScript Support

Full TypeScript definitions are included:

import ExpressQuranAPI from 'express-quran-api';

const api = new ExpressQuranAPI({
  port: 4000,
  extraLanguages: ['en', 'ur']
});

Author

bluezly

• Website: www.bluezly.exid.me
• Discord: bluezly

License

MIT