Quran API Express

A flexible and easy-to-use Express.js API for accessing Quran data, including surahs, verses, search functionality, and daily verses.

Features

• 📖 Complete Quran data with Arabic text and translations
• 🔍 Powerful search functionality (text and reference-based)
• 🎲 Random verse generator
• 📅 Daily verse (same verse for everyone on the same day)
• ⚙️ Highly configurable
• 🚀 Easy to integrate into existing Express apps
• 🔒 CORS support with customization options

Installation

npm install quran-api-express

Quick Start

Standalone Server

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

const api = new QuranAPI();
api.start();

This will start the API server on port 3000 (or the PORT environment variable).

With Custom Configuration

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

const api = new QuranAPI({
    port: 5000,
    basePath: '/v1',
    cors: { 
        origin: 'https://yourwebsite.com',
        credentials: true 
    }
});

api.start(() => {
    console.log('Quran API is ready!');
});

Integrate with Existing Express App

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

const mainApp = express();
const quranAPI = new QuranAPI({ basePath: '/quran' });

// Wait for data to initialize
quranAPI.initialize().then(() => {
    // Mount the Quran API
    mainApp.use(quranAPI.getApp());
    
    // Add your own routes
    mainApp.get('/', (req, res) => {
        res.json({ message: 'Assalamuakeik!' });
    });
    
    mainApp.listen(3000, () => {
        console.log('Server running on port 3000');
    });
});

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | port | Number | 3000 | Port number for the server | | basePath | String | '/api' | Base path for all API routes | | dataSource | String | Default Google Drive ID | Custom data source file ID | | cors | Object | {} | CORS configuration options | | middleware | Array | [] | Array of custom Express middleware |

API Endpoints

Base URL

http://localhost:3000/api

1. Health Check

GET /health

Check if the API is initialized and ready.

curl http://localhost:3000/api/health

Response:

{
  "status": "ok",
  "initialized": true,
  "timestamp": "2024-12-10T10:30:00.000Z"
}

2. Get All Surahs

GET /surah

Returns metadata for all 114 surahs.

curl http://localhost:3000/api/surah

Response:

{
  "code": 200,
  "status": "OK",
  "data": [
    {
      "number": 1,
      "name": "الفاتحة",
      "transliteration": "Al-Fatihah",
      "translation": "The Opening",
      "type": "Meccan",
      "total_verses": 7
    },
    ...
  ]
}

3. Get Specific Surah

GET /surah/:id

Returns complete surah data with all verses.

curl http://localhost:3000/api/surah/1

Parameters:

• id (required): Surah number (1-114)

Response:

{
  "code": 200,
  "status": "OK",
  "data": {
    "id": 1,
    "name": "الفاتحة",
    "transliteration": "Al-Fatihah",
    "translation": "The Opening",
    "type": "Meccan",
    "total_verses": 7,
    "verses": [
      {
        "id": 1,
        "text": "بِسْمِ اللَّهِ الرَّحْمَٰنِ الرَّحِيمِ",
        "translation": "In the name of Allah, the Entirely Merciful, the Especially Merciful."
      },
      ...
    ]
  }
}

4. Search Verses

GET /search?q=query&limit=50

Search for verses by text or reference.

# Text search
curl "http://localhost:3000/api/search?q=mercy"

# Reference search (Surah:Ayah)
curl "http://localhost:3000/api/search?q=2:255"

Query Parameters:

• q (required): Search query (minimum 2 characters)
• limit (optional): Maximum results to return (default: 50)

Response:

{
  "query": "mercy",
  "count": 123,
  "limit": 50,
  "data": [
    {
      "surah_number": 1,
      "surah_name": "Al-Fatihah",
      "surah_name_ar": "الفاتحة",
      "surah_name_translation": "The Opening",
      "ayah_number": 1,
      "text": "بِسْمِ اللَّهِ الرَّحْمَٰنِ الرَّحِيمِ",
      "translation": "In the name of Allah, the Entirely Merciful, the Especially Merciful."
    },
    ...
  ]
}

5. Get Specific Verse

GET /quran/:surahId/:ayahId

Get a specific verse by surah and ayah number.

curl http://localhost:3000/api/quran/2/255

Parameters:

• surahId (required): Surah number
• ayahId (required): Ayah number within the surah

Response:

{
  "code": 200,
  "status": "OK",
  "data": {
    "surah_number": 2,
    "surah_name": "Al-Baqarah",
    "surah_name_ar": "البقرة",
    "surah_name_translation": "The Cow",
    "ayah_number": 255,
    "text": "اللَّهُ لَا إِلَٰهَ إِلَّا هُوَ...",
    "translation": "Allah - there is no deity except Him..."
  }
}

6. Get Random Verse

GET /ayah/random

Returns a random verse from the Quran.

curl http://localhost:3000/api/ayah/random

Response:

{
  "code": 200,
  "status": "OK",
  "data": {
    "surah_number": 18,
    "surah_name": "Al-Kahf",
    "ayah_number": 10,
    "text": "...",
    "translation": "..."
  }
}

7. Get Daily Verse

GET /daily

Returns the same verse for everyone on the same day (based on UTC date).

curl http://localhost:3000/api/daily

Response:

{
  "code": 200,
  "status": "OK",
  "meta": {
    "date_utc": "2024-12-10"
  },
  "data": {
    "surah_number": 3,
    "surah_name": "Al 'Imran",
    "ayah_number": 191,
    "text": "...",
    "translation": "..."
  }
}

Advanced Usage

Access Raw Cache Data

const api = new QuranAPI();

await api.initialize();

const cache = api.getCache();
console.log(`Total verses: ${cache.flatVerses.length}`);
console.log(`Total surahs: ${cache.meta.length}`);

Add Custom Middleware

const morgan = require('morgan');

const api = new QuranAPI({
    middleware: [
        morgan('combined'),
        (req, res, next) => {
            console.log('Custom middleware');
            next();
        }
    ]
});

api.start();

Custom Data Source

If you have your own Google Drive file with Quran data in the same format:

const api = new QuranAPI({
    dataSource: 'your-google-drive-file-id'
});

api.start();

Error Handling

The API uses standard HTTP status codes:

• 200 - Success
• 400 - Bad Request (invalid parameters)
• 404 - Not Found (surah/verse doesn't exist)
• 503 - Service Unavailable (data still loading)

Example Error Response:

{
  "error": "Invalid Surah ID. Must be between 1 and 114"
}

Environment Variables

• PORT - Server port (default: 3000)

PORT=5000 node index.js

Requirements

• Node.js >= 14.0.0
• Express.js >= 4.18.0

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Quran data source
• Express.js framework
• All contributors

Support

If you encounter any issues or have questions, please open an issue on GitHub.

Author

Sanni Olayinka Aliyu - @sanni4susx

Project Link: https://github.com/HouriDomains/quran-api-express