Update README.md
Browse files
README.md
CHANGED
|
@@ -8,5 +8,253 @@ pinned: false
|
|
| 8 |
license: mit
|
| 9 |
short_description: Official Repo/Space containing and running the Kalamalah API
|
| 10 |
---
|
|
|
|
|
|
|
| 11 |
|
| 12 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 8 |
license: mit
|
| 9 |
short_description: Official Repo/Space containing and running the Kalamalah API
|
| 10 |
---
|
| 11 |
+
# Kalamalah CDN Dataset
|
| 12 |
+
This dataset contains all Quran data, audio recitations, and mushaf pages for the Kalamalah Quran API!
|
| 13 |
|
| 14 |
+
# Kalamalah API Documentation and CDN File Path Plan
|
| 15 |
+
|
| 16 |
+
## Base URL
|
| 17 |
+
- **Production**: `https://api.kalamalah.com`
|
| 18 |
+
|
| 19 |
+
## CDN Structure (Both Local & Hugging Face Hub)
|
| 20 |
+
The API uses either local files or Hugging Face Hub dataset `Kalamalah/cdn` as the CDN. The structure is identical for both:
|
| 21 |
+
```
|
| 22 |
+
cdn/
|
| 23 |
+
โโโ api_data/
|
| 24 |
+
โ โโโ surahs.json
|
| 25 |
+
โ โโโ editions.json
|
| 26 |
+
โ โโโ surah/
|
| 27 |
+
โ โโโ 1/
|
| 28 |
+
โ โ โโโ uthmani.json (Arabic text)
|
| 29 |
+
โ โ โโโ en.sahih.json (English translation)
|
| 30 |
+
โ โโโ 2/
|
| 31 |
+
โ โ โโโ ...
|
| 32 |
+
โ โโโ 114/
|
| 33 |
+
โ โโโ ...
|
| 34 |
+
โโโ fonts/
|
| 35 |
+
โ โโโ Kitab-Regular.ttf
|
| 36 |
+
โ โโโ Kitab-Regular.woff2
|
| 37 |
+
โ โโโ Uthmani-Regular.ttf
|
| 38 |
+
โ โโโ Uthmani-Regular.woff2
|
| 39 |
+
โ โโโ SF-ProUI.ttf
|
| 40 |
+
โ โโโ SF-ProUI.woff2
|
| 41 |
+
โ โโโ SF-ArabicUI.ttf
|
| 42 |
+
โ โโโ SF-ArabicUI.woff2
|
| 43 |
+
โโโ reciters/
|
| 44 |
+
โ โโโ profiles-images/
|
| 45 |
+
โ โ โโโ haitham-dokin-profile.jpg
|
| 46 |
+
โ โ โโโ yasser-aldosari-profile.png
|
| 47 |
+
โ โ โโโ ... (all reciter profile images)
|
| 48 |
+
โ โโโ athan/
|
| 49 |
+
โ โ โโโ (athan mp3 files)
|
| 50 |
+
โ โโโ audio/
|
| 51 |
+
โ โโโ haitham-al-dukhin/
|
| 52 |
+
โ โ โโโ murattal/
|
| 53 |
+
โ โ โโโ 001.mp3
|
| 54 |
+
โ โ โโโ 002.mp3
|
| 55 |
+
โ โ โโโ ... 114.mp3
|
| 56 |
+
โ โโโ yasser-al-dossari/
|
| 57 |
+
โ โ โโโ murattal/
|
| 58 |
+
โ โ โโโ ...
|
| 59 |
+
โ โโโ abdul-baset/
|
| 60 |
+
โ โ โโโ mujawwad/
|
| 61 |
+
โ โ โ โโโ ...
|
| 62 |
+
โ โ โโโ murattal/
|
| 63 |
+
โ โ โโโ ...
|
| 64 |
+
โ โโโ khalil-al-husary/
|
| 65 |
+
โ โ โโโ murattal/
|
| 66 |
+
โ โ โ โโโ ...
|
| 67 |
+
โ โ โโโ muallim/
|
| 68 |
+
โ โ โโโ ...
|
| 69 |
+
โ โโโ siddiq-minshawi/
|
| 70 |
+
โ โ โโโ murattal/
|
| 71 |
+
โ โ โ โโโ ...
|
| 72 |
+
โ โ โโโ kids-repeat/
|
| 73 |
+
โ โ โโโ ...
|
| 74 |
+
โ โโโ (other reciters)
|
| 75 |
+
โโโ mushafs/
|
| 76 |
+
โ โโโ qatar-mushaf/
|
| 77 |
+
โ โโโ 0.jpg
|
| 78 |
+
โ โโโ 1.jpg
|
| 79 |
+
โ โโโ 2.jpg
|
| 80 |
+
โ โโโ ... 604.jpg
|
| 81 |
+
โโโ background_audio/
|
| 82 |
+
โโโ whales.mp3
|
| 83 |
+
```
|
| 84 |
+
|
| 85 |
+
---
|
| 86 |
+
|
| 87 |
+
## API Endpoints
|
| 88 |
+
|
| 89 |
+
### 1. Health Check
|
| 90 |
+
- **Endpoint**: `GET /health`
|
| 91 |
+
- **Description**: Check if API is running
|
| 92 |
+
- **Response**:
|
| 93 |
+
```json
|
| 94 |
+
{ "status": "healthy" }
|
| 95 |
+
```
|
| 96 |
+
|
| 97 |
+
### 2. Root Info
|
| 98 |
+
- **Endpoint**: `GET /`
|
| 99 |
+
- **Description**: Get API overview and available endpoints
|
| 100 |
+
- **Response**:
|
| 101 |
+
```json
|
| 102 |
+
{
|
| 103 |
+
"message": "Welcome to Kalamalah Quran API!",
|
| 104 |
+
"docs": "/docs",
|
| 105 |
+
"endpoints": {
|
| 106 |
+
"quran": "/api/quran/{language}/{surah_number}[/{ayah_number}]",
|
| 107 |
+
"surahs_list": "/api/surahs",
|
| 108 |
+
"reciters": "/api/reciters",
|
| 109 |
+
"audio": "/api/{reciter_name}/{type}/{surah_number}",
|
| 110 |
+
"mushaf": "/api/mushaf/{mushaf_name}/{page_number}",
|
| 111 |
+
"fonts": "/api/fonts.css"
|
| 112 |
+
}
|
| 113 |
+
}
|
| 114 |
+
```
|
| 115 |
+
|
| 116 |
+
### 3. Get All Surahs
|
| 117 |
+
- **Endpoint**: `GET /api/surahs`
|
| 118 |
+
- **Description**: Get list of all 114 surahs with metadata (name, number of ayahs, etc.)
|
| 119 |
+
- **Response**: Array of surah objects
|
| 120 |
+
|
| 121 |
+
### 4. Get All Reciters
|
| 122 |
+
- **Endpoint**: `GET /api/reciters`
|
| 123 |
+
- **Description**: Get list of all reciters with their information
|
| 124 |
+
- **Response**:
|
| 125 |
+
```json
|
| 126 |
+
{
|
| 127 |
+
"haitham-al-dukhin": {
|
| 128 |
+
"name": "Haitham Al Dokhin",
|
| 129 |
+
"arabic_name": "ููุซู
ุงูุฏุฎูู",
|
| 130 |
+
"types": ["murattal"],
|
| 131 |
+
"description": "...",
|
| 132 |
+
"profile_image": "haitham-dokin-profile.jpg"
|
| 133 |
+
},
|
| 134 |
+
"etc etc of course"
|
| 135 |
+
}
|
| 136 |
+
```
|
| 137 |
+
|
| 138 |
+
---
|
| 139 |
+
|
| 140 |
+
### 5. Get Quran Text
|
| 141 |
+
**Endpoints**:
|
| 142 |
+
- `GET /api/quran/{language}/{surah_number}`
|
| 143 |
+
- `GET /api/quran/{language}/{surah_number}/{ayah_number}`
|
| 144 |
+
|
| 145 |
+
**Parameters**:
|
| 146 |
+
- `language`: Language/edition code (e.g., "ar" for Arabic Uthmani, "en" for Sahih English, "tafsir" for Tafsir Muyassar)
|
| 147 |
+
- `surah_number`: 1-114
|
| 148 |
+
- `ayah_number` (optional): Specific ayah number in the surah
|
| 149 |
+
|
| 150 |
+
**Examples**:
|
| 151 |
+
- Arabic text (Surah Al-Fatiha): `https://api.kalamalah.com/api/quran/ar/1`
|
| 152 |
+
- English translation (Surah Al-Baqarah): `https://api.kalamalah.com/api/quran/en/2`
|
| 153 |
+
- Single ayah: `https://api.kalamalah.com/api/quran/ar/1/1`
|
| 154 |
+
|
| 155 |
+
---
|
| 156 |
+
|
| 157 |
+
### 6. Get Mushaf Page
|
| 158 |
+
- **Endpoint**: `GET /api/mushaf/{mushaf_name}/{page_number}`
|
| 159 |
+
- **Description**: Get a page from a specific mushaf as an image
|
| 160 |
+
- **Parameters**:
|
| 161 |
+
- `mushaf_name`: Currently "qatar-mushaf"
|
| 162 |
+
- `page_number`: Page number (0 to 604 for Qatar Mushaf; no leading zeros)
|
| 163 |
+
- **Supported Formats**: .jpg, .jpeg, .png
|
| 164 |
+
- **Example**: `https://api.kalamalah.com/api/mushaf/qatar-mushaf/222`
|
| 165 |
+
|
| 166 |
+
---
|
| 167 |
+
|
| 168 |
+
### 7. Get Reciter Audio
|
| 169 |
+
- **Endpoint**: `GET /api/{reciter_name}/{recitation_type}/{surah_number}`
|
| 170 |
+
- **Description**: Get audio recitation of a surah
|
| 171 |
+
- **Parameters**:
|
| 172 |
+
- `reciter_name`: Reciter slug (from `/api/reciters`)
|
| 173 |
+
- `recitation_type`: Type of recitation (from reciter's "types" array)
|
| 174 |
+
- `surah_number`: 1-114 (can be 3-digit padded or not)
|
| 175 |
+
- **Examples**:
|
| 176 |
+
- `https://api.kalamalah.com/api/yasser-al-dossari/murattal/001`
|
| 177 |
+
- `https://api.kalamalah.com/api/siddiq-minshawi/kids-repeat/1`
|
| 178 |
+
- `https://api.kalamalah.com/api/khalil-al-husary/muallim/2`
|
| 179 |
+
|
| 180 |
+
**Available Reciters & Types**:
|
| 181 |
+
| Reciter Slug | Name | Available Types |
|
| 182 |
+
|--------------|------|-----------------|
|
| 183 |
+
| haitham-al-dukhin | Haitham Al Dokhin | murattal |
|
| 184 |
+
| abdul-rashid-sofi | Abdul-Rasheed Sofi | murattal |
|
| 185 |
+
| yasser-al-dossari | Yasser Al-Dossari | murattal |
|
| 186 |
+
| abdul-baset | Abdul Baset | mujawwad, murattal |
|
| 187 |
+
| khalil-al-husary | Khalil Al-Husary | murattal, muallim, mujawwad, ijazah |
|
| 188 |
+
| siddiq-minshawi | Siddiq Minshawi | murattal, kids-repeat, mujawwad |
|
| 189 |
+
| hani-ar-rifai | Hani Ar-Rifai | murattal |
|
| 190 |
+
| abdurrahmaan-as-sudais | Abdurrahmaan As-Sudais | murattal |
|
| 191 |
+
| maher-al-muaiqly | Maher Al-Muaiqly | murattal |
|
| 192 |
+
| ahmed-al-ajamy | Ahmed Al-Ajamy | murattal |
|
| 193 |
+
| al-huzaifi | Al-Huzaifi | ayah-by-ayah |
|
| 194 |
+
| mishary-rashid-alafasy | Mishary Rashid Alafasy | (types coming soon) |
|
| 195 |
+
|
| 196 |
+
---
|
| 197 |
+
|
| 198 |
+
### 8. Get Reciter Profile Image
|
| 199 |
+
- **Endpoint**: `GET /api/reciter-profile/{reciter_name}`
|
| 200 |
+
- **Description**: Get the profile image of a reciter
|
| 201 |
+
- **Example**: `https://api.kalamalah.com/api/reciter-profile/yasser-al-dossari`
|
| 202 |
+
|
| 203 |
+
---
|
| 204 |
+
|
| 205 |
+
### 9. Athan (Call to Prayer)
|
| 206 |
+
**Endpoints**:
|
| 207 |
+
- `GET /api/athan` - List all available athan files
|
| 208 |
+
- `GET /api/athan/{filename}` - Get specific athan audio file
|
| 209 |
+
- **Example**: `https://api.kalamalah.com/api/athan/athan.mp3` (replace with actual filename)
|
| 210 |
+
|
| 211 |
+
---
|
| 212 |
+
|
| 213 |
+
### 10. Background Audio
|
| 214 |
+
**Endpoints**:
|
| 215 |
+
- `GET /api/background-audio` - List all available background audio files
|
| 216 |
+
- `GET /api/background-audio/{filename}` - Get specific background audio
|
| 217 |
+
- **Example**: `https://api.kalamalah.com/api/background-audio/whales.mp3`
|
| 218 |
+
|
| 219 |
+
---
|
| 220 |
+
|
| 221 |
+
### 11. Fonts API (Google Fonts Style)
|
| 222 |
+
**Endpoints**:
|
| 223 |
+
1. **Get Font CSS** - `GET /api/fonts.css`
|
| 224 |
+
- **Parameters**:
|
| 225 |
+
- `family` (optional): Font families to include, separated by `|` (e.g., `Kitab|Uthmani|SF-ProUI`)
|
| 226 |
+
- `display` (optional): Font display strategy (default: `swap`, options: `auto`, `block`, `swap`, `fallback`, `optional`)
|
| 227 |
+
- **Description**: Get `@font-face` rules for your selected fonts (just like Google Fonts!)
|
| 228 |
+
- **Examples**:
|
| 229 |
+
- All fonts: `https://api.kalamalah.com/api/fonts.css`
|
| 230 |
+
- Specific fonts (neat names): `https://api.kalamalah.com/api/fonts.css?family=Kitab|Uthmani|SF-ProUI|SF-ArabicUI`
|
| 231 |
+
- Specific fonts (simple names): `https://api.kalamalah.com/api/fonts.css?family=kitab|uthmani|sfPro|sfArabic`
|
| 232 |
+
- Custom font-display: `https://api.kalamalah.com/api/fonts.css?family=SF-ArabicUI&display=block`
|
| 233 |
+
|
| 234 |
+
2. **Get Font File** - `GET /api/fonts/{filename}`
|
| 235 |
+
- **Parameters**:
|
| 236 |
+
- `filename`: Font file name (e.g., `Kitab-Regular.woff2`)
|
| 237 |
+
- **Description**: Get an individual font file
|
| 238 |
+
- **Example**: `https://api.kalamalah.com/api/fonts/Uthmani-Regular.woff2`
|
| 239 |
+
|
| 240 |
+
**Available Font Families** (both simple and neat names are supported):
|
| 241 |
+
| Neat Name | Simple Name | Description |
|
| 242 |
+
|-----------|-------------|-------------|
|
| 243 |
+
| `Kitab` | `kitab` | Kitab Arabic font |
|
| 244 |
+
| `Uthmani` | `uthmani` | Uthmani Quranic font |
|
| 245 |
+
| `SF-ProUI` | `sfPro` | San Francisco Pro UI (system font) |
|
| 246 |
+
| `SF-ArabicUI` | `sfArabic` | San Francisco Arabic UI (system font) |
|
| 247 |
+
|
| 248 |
+
---
|
| 249 |
+
|
| 250 |
+
## Important Notes
|
| 251 |
+
1. All audio files are in MP3 format
|
| 252 |
+
2. Mushaf pages are JPG/PNG images
|
| 253 |
+
3. Profile images can be JPG, JPEG, or PNG
|
| 254 |
+
4. The API supports both local files and Hugging Face Hub CDN via the `USE_HF_CDN` environment variable
|
| 255 |
+
5. All endpoints support CORS (Cross-Origin Resource Sharing)
|
| 256 |
+
6. Interactive documentation available at `/docs` (Scalar UI)
|
| 257 |
+
|
| 258 |
+
|
| 259 |
+
## Credits
|
| 260 |
+
All content provided by Kalamalah
|