express-quran-api/Readme.md

Simple Quran API with Express

# Express Quran API

[![npm version](https://badge.fury.io/js/express-quran-api.svg)](https://badge.fury.io/js/express-quran-api)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/node/v/express-quran-api.svg)](https://nodejs.org/)

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

```bash
npm install express-quran-api
```

## Quick Start

```javascript
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
```json
[
  {
    "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
```json
[
  {
    "surah": 1,
    "surahName": "الفاتحة",
    "surahTranslation": "The Opening",
    "ayah": 1,
    "text": "بِسْمِ اللَّهِ الرَّحْمَٰنِ الرَّحِيمِ",
    "translation": "In the name of Allah, the Beneficent, the Merciful"
  }
]
```

### Random Ayah Response
```json
{
  "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:

```typescript
import ExpressQuranAPI from 'express-quran-api';

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

## Author

**bluezly**
- Website: [www.bluezly.exid.me](http://www.bluezly.exid.me)
- Discord: bluezly

## License

MIT