--- 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