File size: 9,008 Bytes
a9016b4 3ad3b12 a9016b4 328d5f1 a9016b4 328d5f1 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 | ---
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
|