|
Download README.md from Kalamalah/api: direct link, hf CLI and curl.
- Browser
- Download file 9.01 kB
-
https://huggingface.co/spaces/Kalamalah/api/resolve/main/README.md
- Command line
-
hf download hf://spaces/Kalamalah/api/README.md
-
curl -L -o README.md https://huggingface.co/spaces/Kalamalah/api/resolve/main/README.md
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 | |