UmmahAPI Documentation

Getting Started

UmmahAPI is a free Islamic REST API with 12 services: Quran (12 languages), Hadith, Tafsir, Prayer Times, Qibla, Islamic Names, Zakat Calculator, Moon Sighting, Hijri Calendar, Duas, 99 Names of Allah, and Word-by-Word Quran. No signup required.

Quran

Complete Quran with Uthmani and IndoPak scripts, tajweed markings, transliteration, 12 translations, audio from 12 reciters, mushaf pages, and search.

`GET /api/quran`

Get information about available translations, reciters, and statistics.

`GET /api/quran/surahs`

Get metadata for all surahs including name, verse count, revelation place, and audio.

`GET /api/quran/surah/{number}`

Get a complete surah with Arabic text, transliteration, translations, and audio for every verse.

number (integer, required) — Surah number (1–114)
script (string, optional) — Arabic script: uthmani (default), indopak, tajweed (Uthmani with color markings), or all
translation (string, optional) — Specific translation: sahih_international, pickthall, yusuf_ali, urdu, turkish, indonesian, french, german, bengali, spanish, malay, bosnian
reciter (integer, optional) — Reciter ID (use /api/quran/reciters for list)

`GET /api/quran/surah/{surah}/ayah/{ayah}`

Get a single verse with Arabic, transliteration, all translations, and audio from all reciters.

surah (integer, required) — Surah number (1–114)
ayah (integer, required) — Ayah number
script (string, optional) — Arabic script: uthmani (default), indopak, tajweed, or all

`GET /api/quran/random`

Get a random verse from the Quran. Great for daily verse widgets.

`GET /api/quran/search`

Search across translations and transliterations for matching verses.

q (string, required) — Search term
translation (string, optional) — Translation to search (default: sahih_international)
limit (integer, optional) — Max results 1–50 (default: 25)

`GET /api/quran/juz/{number}`

Get all verses in a juz (1–30). Used for daily reading plans.

number (integer, required) — Juz number (1–30)

`GET /api/quran/page/{number}`

Word-by-word data for a Madina Mushaf page (1–604). Includes Uthmani text, tajweed HTML, line numbers (1–15), and verse references. Ideal for Quran reader apps.

number (integer, required) — Page number (1–604)

`GET /api/quran/reciters`

Get available Quran reciters with their IDs for audio endpoints.

`GET /api/quran/audio/{surah}`

Get audio recitation URLs for a full surah. Optionally specify a reciter for ayah-by-ayah breakdown.

surah (integer, required) — Surah number (1–114)
reciter (integer, optional) — Reciter ID for per-ayah audio

`GET /api/quran/audio/{surah}/{ayah}`

Get audio recitation URLs for a specific ayah from all reciters.

surah (integer, required) — Surah number
ayah (integer, required) — Ayah number

Word-by-Word

Per-word Arabic text, transliteration, and English meaning for every word in the Quran.

`GET /api/quran/words/{surah}/{ayah}`

Get every word of a specific verse with Arabic, transliteration, and English meaning.

surah (integer, required) — Surah number (1–114)
ayah (integer, required) — Ayah number

`GET /api/quran/words/{surah}`

Get word-by-word breakdown for all verses of a surah.

surah (integer, required) — Surah number (1–114)

Mutashabihat

Similar/resembling verses in the Quran. 1,200+ verses with 2,300+ pairs across 81 surahs. Helps huffaz identify commonly confused verses.

`GET /api/quran/mutashabihat`

Get info about the mutashabihat (similar verses) dataset. 1,200+ verses with 2,300+ similar-verse pairs across 81 surahs. Useful for huffaz to identify commonly confused verses.

`GET /api/quran/mutashabihat/random`

Get a random verse that has similar verses, along with all its similar verses. Great for study/quiz apps.

`GET /api/quran/mutashabihat/{surah}`

Get all verses in a surah that have known similar verses elsewhere in the Quran. Paginated.

surah (integer, required) — Surah number (1–114)
page (integer, optional) — Page number (default: 1)
limit (integer, optional) — Results per page (default: 20, max: 50)

`GET /api/quran/mutashabihat/{surah}/{ayah}`

Get all verses similar to a specific ayah. Returns Arabic text and English translation for both the source and similar verses. Returns 404 if no similar verses are known.

surah (integer, required) — Surah number (1–114)
ayah (integer, required) — Ayah number

Tafsir

Scholarly Quranic commentary. Ibn Kathir and Ma'arif al-Qur'an in English, Muyassar and Ibn Kathir in Arabic.

`GET /api/tafsir`

List all available tafsir sources with keys, names, languages, and authors.

`GET /api/tafsir/{tafsir}/surah/{surah}/ayah/{ayah}`

Get tafsir commentary for a specific verse. Use "all" as tafsir key to get all tafasir at once.

tafsir (string, required) — Tafsir key: ibn_kathir, maarif, muyassar, ibn_kathir_ar, or "all"
surah (integer, required) — Surah number (1–114)
ayah (integer, required) — Ayah number

`GET /api/tafsir/{tafsir}/surah/{surah}`

Get tafsir commentary for all ayahs in a surah.

tafsir (string, required) — Tafsir key: ibn_kathir, maarif, muyassar, ibn_kathir_ar, or "all"
surah (integer, required) — Surah number (1–114)

Hadith

36,000+ hadiths from 10 collections: Bukhari, Muslim, Abu Dawud, Tirmidhi, Ibn Majah, Nasai, Malik, Nawawi's 40, 40 Hadith Qudsi, and Shah Waliullah's 40.

`GET /api/hadith/collections`

Get all available hadith collections with names and hadith counts.

`GET /api/hadith/random`

Get a random hadith. Optionally filter by collection.

collection (string, optional) — Collection key: bukhari, muslim, abudawud, tirmidhi, ibnmajah, nasai, malik

`GET /api/hadith/search`

Search hadith text across all or a specific collection.

q (string, required) — Search term
collection (string, optional) — Limit search to a collection
limit (integer, optional) — Max results (default: 25)

`GET /api/hadith/{collection}`

Paginated browse of a hadith collection.

collection (string, required) — Collection: bukhari, muslim, abudawud, tirmidhi, ibnmajah, nasai, malik
page (integer, optional) — Page number (default: 1)
limit (integer, optional) — Hadiths per page (default: 50)

`GET /api/hadith/{collection}/{number}`

Get a specific hadith by its number within a collection.

collection (string, required) — Collection key
number (string, required) — Hadith number

Prayer Times

Accurate prayer times for any location. 23 calculation methods (with short aliases), madhab support, high-latitude rules, monthly timetable, and Ramadan schedule.

`GET /api/prayer-times`

Calculate Fajr, Dhuhr, Asr, Maghrib, and Isha for any location with timezone support. Returns both HH:MM format (prayer_times) and full ISO 8601 timestamps (prayer_datetimes).

lat (number, required) — Latitude (-90 to 90)
lng (number, required) — Longitude (-180 to 180)
date (string, optional) — Date as YYYY-MM-DD (default: today)
method (string, optional) — Calculation method or alias (e.g. MWL, Egypt, Makkah). Default: MuslimWorldLeague. Full list: /api/prayer-times/methods Options: MuslimWorldLeague, Egyptian, Karachi, UmmAlQura, Dubai, MoonsightingCommittee, NorthAmerica, ISNA, Kuwait, Qatar, Singapore, Turkey, Diyanet, Tehran, JAKIM, UOIF, Gulf, Algeria, Tunisia, Morocco, Jordan, Palestine, Jafari.
madhab (string, optional) — Hanafi (later Asr) or Shafi (earlier Asr) Options: Hanafi, Shafi.
timezone (string, optional) — IANA timezone (e.g. America/New_York)
highLatitudeRule (string, optional) — Twilight rule for far-north/south locations (above ~48°). Pass recommended for usable summer Fajr/Isha. Default keeps standard calculation. Options: recommended, MiddleOfNight, SeventhOfNight, TwilightAngle.

`GET /api/prayer-methods`

List all available prayer time calculation methods with descriptions.

`GET /api/prayer-times/methods`

Discover every calculation method, its accepted short aliases (MWL, Egypt, Makkah, Shia...), the madhabs, and the high-latitude rule options. Use this to avoid guessing method names.

`GET /api/prayer-times/month`

Get prayer times for every day of a month. Great for caching in mobile apps.

lat (number, required) — Latitude
lng (number, required) — Longitude
month (integer, optional) — Month 1–12 (default: current)
year (integer, optional) — Year (default: current)
method (string, optional) — Calculation method
madhab (string, optional) — Hanafi or Shafi Options: Hanafi, Shafi.
timezone (string, optional) — IANA timezone
highLatitudeRule (string, optional) — Twilight rule for high latitudes (recommended for usable summer times) Options: recommended, MiddleOfNight, SeventhOfNight, TwilightAngle.

`GET /api/ramadan/{year}`

Full Ramadan timetable with Suhoor (Fajr) and Iftar (Maghrib) for all 30 days, plus thirds of Ramadan.

year (integer, required) — Gregorian year
lat (number, required) — Latitude
lng (number, required) — Longitude
method (string, optional) — Calculation method
madhab (string, optional) — Hanafi or Shafi Options: Hanafi, Shafi.
timezone (string, optional) — IANA timezone
highLatitudeRule (string, optional) — Twilight rule for high latitudes (recommended for usable summer times) Options: recommended, MiddleOfNight, SeventhOfNight, TwilightAngle.

Qibla Direction

Precise compass bearing to the Kaaba using spherical trigonometry. Distance in km included.

`GET /api/qibla`

Get the compass bearing and distance to the Kaaba from any coordinates.

lat (number, required) — Latitude (-90 to 90)
lng (number, required) — Longitude (-180 to 180)

Islamic Calendar

Gregorian/Hijri conversion, today's Islamic date, month names, and major events.

`GET /api/hijri-date`

Convert a Gregorian date to Hijri calendar date.

date (string, optional) — Date as YYYY-MM-DD (default: today)

`GET /api/gregorian-date`

Convert a Hijri date to Gregorian calendar date.

year (integer, required) — Hijri year
month (integer, required) — Hijri month (1–12)
day (integer, required) — Hijri day (1–30)

`GET /api/today-hijri`

Get the current date in the Islamic calendar.

`GET /api/islamic-months`

Get all 12 Islamic month names with significance.

`GET /api/islamic-events`

Get major Islamic events and observances.

Duas

126 authentic duas from Quran and Sunnah across 27 categories.

`GET /api/duas`

Get the complete collection of duas with Arabic, transliteration, translation, and sources.

`GET /api/duas/categories`

List all categories (morning, evening, travel, prayer, etc.) with counts.

`GET /api/duas/random`

Get a random supplication. Great for daily widgets.

`GET /api/duas/search`

Search duas by title, translation, transliteration, or category.

q (string, required) — Search term

`GET /api/duas/category/{category}`

Get all duas in a specific category.

category (string, required) — Category ID (use /api/duas/categories for list)

`GET /api/duas/{id}`

Get a specific dua by its ID number.

id (integer, required) — Dua ID

99 Names of Allah

Asma ul Husna with Arabic, transliteration, meanings, search, and daily recitation groups.

`GET /api/asma-ul-husna`

Get all 99 beautiful names of Allah with Arabic, transliteration, and meanings.

`GET /api/asma-ul-husna/{number}`

Get a specific name by its number (1–99).

number (integer, required) — Name number (1–99)

`GET /api/asma-ul-husna/random`

Get a random name for daily reflection.

`GET /api/asma-ul-husna/search`

Search names by meaning or transliteration.

q (string, required) — Search term

`GET /api/asma-ul-husna/daily/{day}`

Get names recommended for a specific day of the week.

day (integer, required) — Day of week (1=Monday … 7=Sunday)

Islamic Names

210 curated Islamic names with Arabic script, transliteration, meanings, origins, and root letters. Filter by gender, search by meaning.

`GET /api/names`

Get a paginated list of Islamic names. Filter by gender (male/female) or origin.

gender (string, optional) — Filter by gender: male or female Options: male, female.
origin (string, optional) — Filter by origin (e.g. Arabic, Persian)
page (integer, optional) — Page number (default: 1)
limit (integer, optional) — Results per page (default: 100, max: 210)

`GET /api/names/search`

Search Islamic names by name, Arabic text, meaning, or notes.

q (string, required) — Search term (e.g. "light", "mercy", "نور")
limit (integer, optional) — Max results (default: 25, max: 50)

`GET /api/names/random`

Get a random Islamic name. Optionally filter by gender.

gender (string, optional) — Filter by gender: male or female Options: male, female.

`GET /api/names/{id}`

Get a specific Islamic name by its ID (1–210).

id (integer, required) — Name ID (1–210)

Zakat Calculator

Calculate obligatory Zakat (2.5%) on zakatable wealth. Live gold and silver prices are filled in automatically, so you do not have to supply them. Supports cash, gold, silver, stocks, business goods, investments, and liabilities. Agricultural Zakat (Ushr) also supported.

`GET /api/zakat/info`

Get comprehensive educational information about Zakat: definition, conditions, eligible recipients, zakatable assets, hawl, and the four schools of thought.

`GET /api/zakat/prices`

Get the current gold and silver spot price per gram, plus the gold and silver nisab values. Prices refresh from live market data every hour and are shared from a central cache. Add a currency for local values.

currency (string, optional) — ISO currency code for the prices (USD, GBP, EUR, PKR, SAR, INR, ...)

`GET /api/zakat/nisab`

Get the gold and silver nisab thresholds and their monetary value. Live prices are filled in automatically. Pass your own prices to override, or a currency for local values.

currency (string, optional) — ISO currency code for auto-filled prices (USD, GBP, PKR, ...)
gold_price_per_gram (number, optional) — Optional. Overrides the auto-filled gold price per gram
silver_price_per_gram (number, optional) — Optional. Overrides the auto-filled silver price per gram

`POST /api/zakat/calculate`

Calculate Zakat due on total zakatable wealth. Live gold and silver prices are filled in automatically when you do not provide them. Deducts liabilities before computing.

cash (number, optional) — Cash and bank savings (monetary value)
currency (string, optional) — ISO currency code for auto-filled prices (USD, GBP, PKR, ...)
gold_grams (number, optional) — Gold owned in grams
silver_grams (number, optional) — Silver owned in grams
gold_price_per_gram (number, optional) — Optional. Overrides the auto-filled live gold price per gram
silver_price_per_gram (number, optional) — Optional. Overrides the auto-filled live silver price per gram
nisab_standard (string, optional) — Nisab standard: gold (default) or silver Options: gold, silver.
stocks (number, optional) — Monetary value of stocks/shares
business_goods (number, optional) — Monetary value of business/trade inventory
other_investments (number, optional) — Monetary value of other investments
liabilities (number, optional) — Debts/liabilities to deduct from zakatable wealth

`POST /api/zakat/agriculture`

Calculate Ushr on agricultural produce. 10% for rain-fed crops, 5% for irrigated crops. No hawl required.

value (number, required) — Monetary value of the agricultural produce
water_source (string, optional) — Water source: rain (10%) or irrigation (5%) Options: rain, irrigation.

Moon Sighting

Current Hijri date, moon phase, crescent visibility, upcoming new moons, and Gregorian ↔ Hijri date conversion using the Kuwaiti tabular algorithm.

`GET /api/moon`

Get the current Hijri date with month name and sacred month flag, plus moon phase, illumination, crescent visibility, and next new moon date.

date (string, optional) — Date as YYYY-MM-DD (default: today)

`GET /api/moon/phases`

Get upcoming astronomical new moon (conjunction) dates with expected crescent sighting dates and Hijri month context.

count (integer, optional) — Number of new moons to return (default: 12, max: 24)

`GET /api/moon/months`

Get all 12 Islamic months with Arabic names, sacred month flags, and significance notes.

`GET /api/moon/hijri`

Convert a Gregorian date to its Hijri equivalent using the Kuwaiti tabular algorithm.

year (integer, required) — Gregorian year (622–2500)
month (integer, required) — Month (1–12)
day (integer, required) — Day (1–31)

`GET /api/moon/gregorian`

Convert a Hijri date to its Gregorian equivalent.

year (integer, required) — Hijri year (1–2000)
month (integer, required) — Hijri month (1–12)
day (integer, required) — Hijri day (1–30)

API Key & Usage

Optional API key for 5x higher rate limits. All endpoints work without a key.

`GET /api/usage`

View your request counts by endpoint, daily breakdown, and account info.

apikey (string, required) — Your API key

`GET /api/health`

Check the health status of the API and all services.

`GET /api/limits`

Get current rate limit tiers and policies.