api / README.md
yxqo41main's picture
Update README.md
328d5f1 verified
|
Raw History Blame Contribute Delete
9.01 kB
---
title: API
emoji: ๐Ÿ’ป
colorFrom: green
colorTo: gray
sdk: docker
pinned: false
license: mit
short_description: Official Repo/Space containing and running the Kalamalah API
---
# Kalamalah CDN Dataset
This dataset contains all Quran data, audio recitations, and mushaf pages for the Kalamalah Quran API!
# Kalamalah API Documentation and CDN File Path Plan
## Base URL
- **Production**: `https://api.kalamalah.com`
## CDN Structure (Both Local & Hugging Face Hub)
The API uses either local files or Hugging Face Hub dataset `Kalamalah/cdn` as the CDN. The structure is identical for both:
```
cdn/
โ”œโ”€โ”€ api_data/
โ”‚ โ”œโ”€โ”€ surahs.json
โ”‚ โ”œโ”€โ”€ editions.json
โ”‚ โ””โ”€โ”€ surah/
โ”‚ โ”œโ”€โ”€ 1/
โ”‚ โ”‚ โ”œโ”€โ”€ uthmani.json (Arabic text)
โ”‚ โ”‚ โ””โ”€โ”€ en.sahih.json (English translation)
โ”‚ โ”œโ”€โ”€ 2/
โ”‚ โ”‚ โ””โ”€โ”€ ...
โ”‚ โ””โ”€โ”€ 114/
โ”‚ โ””โ”€โ”€ ...
โ”œโ”€โ”€ fonts/
โ”‚ โ”œโ”€โ”€ Kitab-Regular.ttf
โ”‚ โ”œโ”€โ”€ Kitab-Regular.woff2
โ”‚ โ”œโ”€โ”€ Uthmani-Regular.ttf
โ”‚ โ”œโ”€โ”€ Uthmani-Regular.woff2
โ”‚ โ”œโ”€โ”€ SF-ProUI.ttf
โ”‚ โ”œโ”€โ”€ SF-ProUI.woff2
โ”‚ โ”œโ”€โ”€ SF-ArabicUI.ttf
โ”‚ โ””โ”€โ”€ SF-ArabicUI.woff2
โ”œโ”€โ”€ reciters/
โ”‚ โ”œโ”€โ”€ profiles-images/
โ”‚ โ”‚ โ”œโ”€โ”€ haitham-dokin-profile.jpg
โ”‚ โ”‚ โ”œโ”€โ”€ yasser-aldosari-profile.png
โ”‚ โ”‚ โ””โ”€โ”€ ... (all reciter profile images)
โ”‚ โ”œโ”€โ”€ athan/
โ”‚ โ”‚ โ””โ”€โ”€ (athan mp3 files)
โ”‚ โ””โ”€โ”€ audio/
โ”‚ โ”œโ”€โ”€ haitham-al-dukhin/
โ”‚ โ”‚ โ””โ”€โ”€ murattal/
โ”‚ โ”‚ โ”œโ”€โ”€ 001.mp3
โ”‚ โ”‚ โ”œโ”€โ”€ 002.mp3
โ”‚ โ”‚ โ””โ”€โ”€ ... 114.mp3
โ”‚ โ”œโ”€โ”€ yasser-al-dossari/
โ”‚ โ”‚ โ””โ”€โ”€ murattal/
โ”‚ โ”‚ โ””โ”€โ”€ ...
โ”‚ โ”œโ”€โ”€ abdul-baset/
โ”‚ โ”‚ โ”œโ”€โ”€ mujawwad/
โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ ...
โ”‚ โ”‚ โ””โ”€โ”€ murattal/
โ”‚ โ”‚ โ””โ”€โ”€ ...
โ”‚ โ”œโ”€โ”€ khalil-al-husary/
โ”‚ โ”‚ โ”œโ”€โ”€ murattal/
โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ ...
โ”‚ โ”‚ โ””โ”€โ”€ muallim/
โ”‚ โ”‚ โ””โ”€โ”€ ...
โ”‚ โ”œโ”€โ”€ siddiq-minshawi/
โ”‚ โ”‚ โ”œโ”€โ”€ murattal/
โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ ...
โ”‚ โ”‚ โ””โ”€โ”€ kids-repeat/
โ”‚ โ”‚ โ””โ”€โ”€ ...
โ”‚ โ””โ”€โ”€ (other reciters)
โ”œโ”€โ”€ mushafs/
โ”‚ โ””โ”€โ”€ qatar-mushaf/
โ”‚ โ”œโ”€โ”€ 0.jpg
โ”‚ โ”œโ”€โ”€ 1.jpg
โ”‚ โ”œโ”€โ”€ 2.jpg
โ”‚ โ””โ”€โ”€ ... 604.jpg
โ””โ”€โ”€ background_audio/
โ””โ”€โ”€ whales.mp3
```
---
## API Endpoints
### 1. Health Check
- **Endpoint**: `GET /health`
- **Description**: Check if API is running
- **Response**:
```json
{ "status": "healthy" }
```
### 2. Root Info
- **Endpoint**: `GET /`
- **Description**: Get API overview and available endpoints
- **Response**:
```json
{
"message": "Welcome to Kalamalah Quran API!",
"docs": "/docs",
"endpoints": {
"quran": "/api/quran/{language}/{surah_number}[/{ayah_number}]",
"surahs_list": "/api/surahs",
"reciters": "/api/reciters",
"audio": "/api/{reciter_name}/{type}/{surah_number}",
"mushaf": "/api/mushaf/{mushaf_name}/{page_number}",
"fonts": "/api/fonts.css"
}
}
```
### 3. Get All Surahs
- **Endpoint**: `GET /api/surahs`
- **Description**: Get list of all 114 surahs with metadata (name, number of ayahs, etc.)
- **Response**: Array of surah objects
### 4. Get All Reciters
- **Endpoint**: `GET /api/reciters`
- **Description**: Get list of all reciters with their information
- **Response**:
```json
{
"haitham-al-dukhin": {
"name": "Haitham Al Dokhin",
"arabic_name": "ู‡ูŠุซู… ุงู„ุฏุฎูŠู†",
"types": ["murattal"],
"description": "...",
"profile_image": "haitham-dokin-profile.jpg"
},
"etc etc of course"
}
```
---
### 5. Get Quran Text
**Endpoints**:
- `GET /api/quran/{language}/{surah_number}`
- `GET /api/quran/{language}/{surah_number}/{ayah_number}`
**Parameters**:
- `language`: Language/edition code (e.g., "ar" for Arabic Uthmani, "en" for Sahih English, "tafsir" for Tafsir Muyassar)
- `surah_number`: 1-114
- `ayah_number` (optional): Specific ayah number in the surah
**Examples**:
- Arabic text (Surah Al-Fatiha): `https://api.kalamalah.com/api/quran/ar/1`
- English translation (Surah Al-Baqarah): `https://api.kalamalah.com/api/quran/en/2`
- Single ayah: `https://api.kalamalah.com/api/quran/ar/1/1`
---
### 6. Get Mushaf Page
- **Endpoint**: `GET /api/mushaf/{mushaf_name}/{page_number}`
- **Description**: Get a page from a specific mushaf as an image
- **Parameters**:
- `mushaf_name`: Currently "qatar-mushaf"
- `page_number`: Page number (0 to 604 for Qatar Mushaf; no leading zeros)
- **Supported Formats**: .jpg, .jpeg, .png
- **Example**: `https://api.kalamalah.com/api/mushaf/qatar-mushaf/222`
---
### 7. Get Reciter Audio
- **Endpoint**: `GET /api/{reciter_name}/{recitation_type}/{surah_number}`
- **Description**: Get audio recitation of a surah
- **Parameters**:
- `reciter_name`: Reciter slug (from `/api/reciters`)
- `recitation_type`: Type of recitation (from reciter's "types" array)
- `surah_number`: 1-114 (can be 3-digit padded or not)
- **Examples**:
- `https://api.kalamalah.com/api/yasser-al-dossari/murattal/001`
- `https://api.kalamalah.com/api/siddiq-minshawi/kids-repeat/1`
- `https://api.kalamalah.com/api/khalil-al-husary/muallim/2`
**Available Reciters & Types**:
| Reciter Slug | Name | Available Types |
|--------------|------|-----------------|
| haitham-al-dukhin | Haitham Al Dokhin | murattal |
| abdul-rashid-sofi | Abdul-Rasheed Sofi | murattal |
| yasser-al-dossari | Yasser Al-Dossari | murattal |
| abdul-baset | Abdul Baset | mujawwad, murattal |
| khalil-al-husary | Khalil Al-Husary | murattal, muallim, mujawwad, ijazah |
| siddiq-minshawi | Siddiq Minshawi | murattal, kids-repeat, mujawwad |
| hani-ar-rifai | Hani Ar-Rifai | murattal |
| abdurrahmaan-as-sudais | Abdurrahmaan As-Sudais | murattal |
| maher-al-muaiqly | Maher Al-Muaiqly | murattal |
| ahmed-al-ajamy | Ahmed Al-Ajamy | murattal |
| al-huzaifi | Al-Huzaifi | ayah-by-ayah |
| mishary-rashid-alafasy | Mishary Rashid Alafasy | (types coming soon) |
---
### 8. Get Reciter Profile Image
- **Endpoint**: `GET /api/reciter-profile/{reciter_name}`
- **Description**: Get the profile image of a reciter
- **Example**: `https://api.kalamalah.com/api/reciter-profile/yasser-al-dossari`
---
### 9. Athan (Call to Prayer)
**Endpoints**:
- `GET /api/athan` - List all available athan files
- `GET /api/athan/{filename}` - Get specific athan audio file
- **Example**: `https://api.kalamalah.com/api/athan/athan.mp3` (replace with actual filename)
---
### 10. Background Audio
**Endpoints**:
- `GET /api/background-audio` - List all available background audio files
- `GET /api/background-audio/{filename}` - Get specific background audio
- **Example**: `https://api.kalamalah.com/api/background-audio/whales.mp3`
---
### 11. Fonts API (Google Fonts Style)
**Endpoints**:
1. **Get Font CSS** - `GET /api/fonts.css`
- **Parameters**:
- `family` (optional): Font families to include, separated by `|` (e.g., `Kitab|Uthmani|SF-ProUI`)
- `display` (optional): Font display strategy (default: `swap`, options: `auto`, `block`, `swap`, `fallback`, `optional`)
- **Description**: Get `@font-face` rules for your selected fonts (just like Google Fonts!)
- **Examples**:
- All fonts: `https://api.kalamalah.com/api/fonts.css`
- Specific fonts (neat names): `https://api.kalamalah.com/api/fonts.css?family=Kitab|Uthmani|SF-ProUI|SF-ArabicUI`
- Specific fonts (simple names): `https://api.kalamalah.com/api/fonts.css?family=kitab|uthmani|sfPro|sfArabic`
- Custom font-display: `https://api.kalamalah.com/api/fonts.css?family=SF-ArabicUI&display=block`
2. **Get Font File** - `GET /api/fonts/{filename}`
- **Parameters**:
- `filename`: Font file name (e.g., `Kitab-Regular.woff2`)
- **Description**: Get an individual font file
- **Example**: `https://api.kalamalah.com/api/fonts/Uthmani-Regular.woff2`
**Available Font Families** (both simple and neat names are supported):
| Neat Name | Simple Name | Description |
|-----------|-------------|-------------|
| `Kitab` | `kitab` | Kitab Arabic font |
| `Uthmani` | `uthmani` | Uthmani Quranic font |
| `SF-ProUI` | `sfPro` | San Francisco Pro UI (system font) |
| `SF-ArabicUI` | `sfArabic` | San Francisco Arabic UI (system font) |
---
## Important Notes
1. All audio files are in MP3 format
2. Mushaf pages are JPG/PNG images
3. Profile images can be JPG, JPEG, or PNG
4. The API supports both local files and Hugging Face Hub CDN via the `USE_HF_CDN` environment variable
5. All endpoints support CORS (Cross-Origin Resource Sharing)
6. Interactive documentation available at `/docs` (Scalar UI)
## Credits
All content provided by Kalamalah