UmmahAPI DOCS

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 13 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 text with <tajweed class=...> rule tags for coloring), or all (returns an object with all three). Unknown values are ignored and reported in a warnings array
  • translation (string, optional) — Specific translation: sahih_international, pickthall, yusuf_ali, urdu, turkish, indonesian, french, german, bengali, spanish, malay, bosnian. Unknown values are ignored and reported in a warnings array
  • reciter (integer, optional) — Reciter ID (use /api/quran/reciters for list). Unknown IDs are ignored and reported in a warnings array

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 (with <tajweed class=...> rule tags), or all. Unknown values are ignored and reported in a warnings array

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: any key listed on /api/quran, or all (default: sahih_international). Unknown values are ignored and reported in a warnings array
  • limit (integer, optional) — Max results 1–50 (default: 25). Values outside the range are clamped

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 markup (text_uthmani_tajweed with <rule class=...> tags), 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, nawawi, qudsi, dehlawi. Unknown keys return 404

GET /api/hadith/search

Search English hadith text across all or a specific collection.

  • q (string, required) — Search term
  • collection (string, optional) — Limit search to a collection: bukhari, muslim, abudawud, tirmidhi, ibnmajah, nasai, malik, nawawi, qudsi, dehlawi. Unknown keys return 400
  • limit (integer, optional) — Max results 1–100 (default: 25)

GET /api/hadith/{collection}

Paginated browse of a hadith collection.

  • collection (string, required) — Collection: bukhari, muslim, abudawud, tirmidhi, ibnmajah, nasai, malik, nawawi, qudsi, dehlawi
  • 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. Some collections use decimal numbers (e.g. tirmidhi 2787.2). Arabic or english is null when the source has no text in that language

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.
  • nearest_city (string, optional) — Pass true to add location.city: the town the coordinates are in (name, country_code, distance_km), or null if none is within 25 km. Town data from GeoNames (CC BY 4.0). Options: true.

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 every day (29 or 30), plus thirds of Ramadan. Uses the Umm al-Qura calendar. Some years (e.g. 2030) contain two Ramadans; ramadans_in_year lists them and hijri_year picks one.

  • year (integer, required) — Gregorian year, 1938 to 2077 (the range the Umm al-Qura calendar covers)
  • 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.
  • hijri_year (integer, optional) — Pick a specific Ramadan when the year has two (e.g. 1452 for the December 2030 one). Default: the first

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 (Umm al-Qura). Supported range: 1937-03-14 to 2077-11-16. The response includes days_in_month for the Hijri month.

  • date (string, optional) — Date as YYYY-MM-DD (default: today in UTC, or in timezone if given)
  • timezone (string, optional) — IANA timezone (e.g. America/New_York) used to decide today's date when date is omitted. Default: UTC

GET /api/gregorian-date

Convert a Hijri date to Gregorian calendar date (Umm al-Qura). Day 30 of a 29-day month returns 400.

  • year (integer, required) — Hijri year (1356–1500)
  • month (integer, required) — Hijri month (1–12)
  • day (integer, required) — Hijri day (1–29 or 1–30, depending on the month)

GET /api/today-hijri

Get the current date in the Islamic calendar. "Today" is the UTC date unless you pass timezone.

  • timezone (string, optional) — IANA timezone (e.g. Asia/Karachi) for the local date. Default: UTC

GET /api/islamic-months

Get all 12 Islamic month names with significance.

GET /api/islamic-events

Get major Islamic events and observances, with the next event after today.

  • timezone (string, optional) — IANA timezone used to decide today's date. Default: UTC

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. prices_used shows which price came from you and which was live. Negative or non-numeric prices return 400.

  • 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. All amounts must be non-negative numbers (plain digits, no commas); anything else returns 400. If you supply only one price and the calculation also needs the other one, pass currency so the live price matches yours; without it the live price is in USD and the response includes a warnings array. prices_used shows the prices actually used.

  • cash (number, optional) — Cash and bank savings (monetary value)
  • currency (string, optional) — ISO currency code of your amounts and prices; auto-filled prices use it (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 (non-negative number)
  • 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 Umm al-Qura calendar.

GET /api/moon

Get the Hijri date with month name, month length and sacred month flag, plus moon age, phase (8 standard phases), illumination, crescent visibility, and the last and next new moon (UTC). Supported range: 1937-03-14 to 2077-11-16.

  • date (string, optional) — Date as YYYY-MM-DD (moon computed at 12:00 UTC), or an ISO date-time such as 2026-10-08T20:30:00-05:00 (date as written, moon at that instant). Default: today in UTC, or in timezone if given
  • timezone (string, optional) — IANA timezone (e.g. Europe/London) used to decide today's date when date is omitted. Default: UTC

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, significance notes, and the real length (days) of each month in a Hijri year from the Umm al-Qura calendar.

  • year (integer, optional) — Hijri year (1356–1500). Default: the current Hijri year

GET /api/moon/hijri

Convert a Gregorian date to its Hijri equivalent using the Umm al-Qura calendar. Supported range: 1937-03-14 to 2077-11-16.

  • year (integer, required) — Gregorian year (1937–2077)
  • month (integer, required) — Month (1–12)
  • day (integer, required) — Day (must exist in that month)

GET /api/moon/gregorian

Convert a Hijri date to its Gregorian equivalent. Day 30 of a 29-day month returns 400.

  • year (integer, required) — Hijri year (1356–1500)
  • month (integer, required) — Hijri month (1–12)
  • day (integer, required) — Hijri day (1–29 or 1–30, depending on the month)

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.

Premier Sponsors
ZikrahZikrah HifzMateHifzMate ilmSpaceilmSpace MyAzanCastMyAzanCast
Home Widgets Blog Support OpenAPI Discord Get Key