🕌 IslamicAPI

العربية | اردو | Bahasa Indonesia | Türkçe

IslamicAPI is an absolute-veracity, offline-first, high-performance structured SDK and reproducible dataset pipeline for Islamic applications. It provides direct, offline access to verified Quranic texts (with Uthmani Hafs script), Hadith collections (Sahih al-Sittah), prayer times calculations across multiple methods, Qibla directions, premium reciter audio mappings, and native mobile client APIs.

---

✨ Quick Start

# JavaScript
npm install @deen/sdk   # or: pnpm add @deen/sdk

# Python
pip install deensdk   # or: pip install -e .

import { getSurah, getAyah, calculatePrayerTimes, getQiblaDirection } from "@deen/sdk";

const surah = getSurah(1);                      // Al-Fatihah with all ayahs
const ayah = getAyah(1, 1);                     // Bismillah with 18 translations
const times = calculatePrayerTimes({            // 7 calculation methods
  latitude: 40.7128, longitude: -74.006,
  method: "isna"
});
const qibla = getQiblaDirection(40.7128, -74.006); // 58.48°

---

📚 Full Function Reference

JavaScript SDK (@deen/sdk)

Function	Description	Returns
getSurah(number)	Full surah with all ayahs, translations, tafsir	{ number, name, englishName, ayahs[] }
getAyah(surah, ayah)	Single ayah with all text variants	{ text: { simple, uthmani, en_sahih, … } }
search(query, opts?)	Full-text Quran search (case-insensitive)	Ayah[] (up to opts.limit, default 25)
getHadith(id)	Hadith by "collection:number"	Hadith with Arabic + English text
randomHadith(opts?)	Random hadith, optional collection filter	Hadith
calculatePrayerTimes(input)	7 calculation methods, flexible names	{ fajr, sunrise, dhuhr, asr, maghrib, isha }
getQiblaDirection(lat, lon)	Compass bearing to Kaaba	number (0–360)
getAudioUrl(reciterId, surah, ayah?)	Audio URL with namespace support (alafasy:mp3quran)	string
getReciterList()	All 363+ reciters	Reciter[]
getFontList()	24 Quranic fonts (Uthmani, Nastaleeq, etc.)	Font[]
getFontCss()	Raw @font-face CSS	string
getAyahTimestamps(surah, reciter?)	Ayah-level start/end times	[{ ayahNumber, start, end }]
getWordTimestamps(surah, ayah, reciter?)	Word-level timestamps	[{ word, start, end }]
getPageTimestamps(page, reciter?)	Timestamps for a Mushaf page	{ page, surahs[] }
getHaramainCompilations()	Haramayn taraweeh/tahajjud recordings	Compilation[]
getHaramainCompilation(id)	Single compilation by ID	Compilation
githubRawUrl(filePath, opts?)	Raw GitHub URL builder	string
createRawDataClient(opts?)	Remote fetch client via GitHub raw	{ loadQuran, loadHadith, … }
downloadToClient(url, fileName?)	Trigger browser download	void

Audio Namespace System

Resolve different recitation styles via colon-separated IDs:

getAudioUrl("sudais:everyayah", 1, 1);  // Ayah-by-ayah (EveryAyah)
getAudioUrl("sudais:haram", 1);         // Masjid al-Haram recording
getAudioUrl("sudais:mp3quran", 1);      // Surah-level (MP3Quran)
getAudioUrl("alafasy:mp3quran", 1);     // Server8 MP3Quran stream

Prayer Times Methods

All methods accept flexible, case-insensitive names:

calculatePrayerTimes({ latitude, longitude, method: "isna" });
calculatePrayerTimes({ latitude, longitude, method: "umm ul qura" });
calculatePrayerTimes({ latitude, longitude, method: "mwl" });

Method	Also accepts
ISNA	isna
UmmAlQura	umm al qura, ummulqura, makkah
MuslimWorldLeague	mwl, muslim world league
Karachi	karachi, university of islamic sciences karachi
Egyptian	egypt, egyptian
Dubai	dubai
MoonsightingCommittee	moonsighting, moonsighting committee

Supports additional options: dhuhrMinutes, madhab ("shafi" / "hanafi").

Python SDK (deensdk)

All functions mirror the JS SDK with Pythonic snake_case naming:

from deensdk import (
    get_surah, get_ayah, search, get_hadith, random_hadith,
    calculate_prayer_times, get_qibla_direction,
    get_audio_url, get_reciter_list,
    get_font_list, get_font_css,
    get_ayah_timestamps, get_word_timestamps, get_page_timestamps,
    get_haramain_compilations, get_haramain_compilation,
    github_raw_url, download_to_server, download_recitation,
    Ayah, Hadith, Surah
)

# Quran with uthmani text
ayah = get_ayah(1, 1)
print(ayah.text["uthmani"])       # Uthmani Hafs script
print(ayah.text["en_sahih"])       # English translation
print(ayah.text["ur_maududi"])     # Urdu translation

# Hadith with collection name
hadith = get_hadith("bukhari:1")
print(hadith.collection_name)     # "Sahih al Bukhari"
print(hadith.text["ar"])          # Arabic text
print(hadith.text["en"])          # English text

# Search (Pydantic-validated results)
results = search("mercy", limit=5)
for ayah in results:
    print(ayah.id, ayah.text.get("en_sahih"))

# Prayer times with extra options
times = calculate_prayer_times(
    latitude=40.7128, longitude=-74.006, method="isna",
    madhab="hanafi", dhuhr_minutes=2
)

# Font CSS
css = get_font_css()  # → @font-face rules for 24 fonts

Models (Pydantic v2)

from deensdk import Ayah, Hadith, Surah, Provenance

# Construct programmatically (snake_case supported via populate_by_name)
ayah = Ayah(
    id="1:1",
    surah_number=1,
    ayah_number=1,
    text={"simple": "بِسْمِ اللَّهِ…", "uthmani": "بِسْمِ ٱللَّهِ…"}
)

---

🗺️ Local HTTP Server

Run the offline-first web server with zero external dependencies:

pnpm dev
# → http://127.0.0.1:3000

Endpoint	Description
GET /health	Health check
GET /quran/surah/:number	Full surah with ayahs
GET /quran/ayah/:surah/:ayah	Single ayah
GET /quran/search?q=	Full-text search
GET /hadith/:id	Hadith by collection:number
GET /hadith/random?collection=	Random hadith
GET /prayer/times?latitude=&longitude=&method=	Prayer times
GET /qibla?latitude=&longitude=	Qibla direction
GET /audio/url?reciterId=&surah=&ayah=	Audio URL
GET /audio/download?reciterId=&surah=	Download recitation
GET /quran/timestamps/ayah?surah=	Ayah timestamps
GET /quran/timestamps/word?surah=&ayah=	Word timestamps
GET /quran/timestamps/page?page=	Page timestamps
GET /fonts	Font list
GET /fonts.css	@font-face CSS
GET /fonts/files/*	WOFF2 font files
GET /haramain/compilations	Haramayn recordings
GET /raw-api	Raw data API index

---

📦 Data Layout

data/
├── quran/normalized/quran.json       # 6236 ayahs, 18 translations, uthmani + simple text
├── quran/normalized/timestamps.json  # Ayah timestamps for all 114 surahs
├── quran/surahs/{1..114}.json        # Per-surah files (optimized for network)
├── hadith/normalized/hadith.json     # 34K+ hadith (Sahih al-Sittah)
├── hadith/normalized/hadith_part_*.json  # Sub-50MB partitions
├── audio/normalized/audio-index.json     # 363 reciters, 27K+ audio entries
├── audio/normalized/haramain-compilations.json
├── fonts/normalized/fonts.json           # 24 Quranic fonts
├── fonts/css/deen-fonts.css              # @font-face CSS
├── fonts/files/*.woff2                   # Actual font files
└── api/index.json                        # Raw data API index

All data is offline-first. Set DEEN_DATA_ROOT to override the data directory.

---

🧪 Testing

# JavaScript tests (node --test)
pnpm test

# Python tests (unittest)
python3 -m unittest tests/test_sdk.py -v

# Rebuild all data from scratch
pnpm sync:updates

---

🤖 AI Agent Integration

This SDK is designed for AI Agents to eliminate hallucination in religious contexts. See AGENTS.md for:

• LangChain/OpenAI Function Calling tool definitions
• OpenAI Assistant API schema definitions
• System prompt templates guaranteeing source-verified responses
• Best practices for absolute-veracity religious QA

---

📱 Mobile SDKs

Platform	File
Flutter/Dart	packages/deen-sdk-flutter/lib/deen_sdk.dart
Swift (iOS/macOS)	packages/deen-sdk-swift/Sources/DeenSDK/DeenSDK.swift
Kotlin (Android)	packages/deen-sdk-kotlin/src/main/kotlin/deensdk/DeenSDK.kt

---

🏗️ Architecture

1. Absolute Veracity: No LLM generation or AI hallucination. Every record has traceable provenance.
2. Offline-First: Core Quran, Hadith, and calculation engines run entirely offline. Large datasets partitioned under 50MB.
3. No ML Dependencies: Word/ayah alignments computed dynamically using optimized proportional algorithms.

Data Pipeline

discover:sources → fetch:datasets → validate:data → normalize:* → build:api-index

Environment Variables

Variable	Default	Description
DEEN_DATA_ROOT	./data	Override data directory path
PORT	3000	Local server port
HOST	127.0.0.1	Local server host

---

📄 License

MIT — see LICENSE.