{
  "name": "TheShia API",
  "version": "v1",
  "rate_limit": "100 uncached requests per minute per IP",
  "services": {
    "prayer-times": {
      "url": "https://theshia.org/api/v1/prayer-times",
      "note": "Jafari (Shia) calculations — AL-Qamar method set, TwilightAngle high-latitude rule, midnight = midpoint(maghrib, next fajr)",
      "location": "lat & lng (decimal degrees, rounded to 2 dp) OR city=<id from /api/v1/cities>",
      "method": "preset id (default Tehran), comma list \"Tehran,Jafari\", \"all\", or \"custom\" (fajrAngle & ishaAngle|ishaInterval [& maghribAngle|maghribInterval])",
      "range": "date=YYYY-MM-DD | year&month | year alone (full year, single method) — budget: days × methods ≤ 496",
      "tz": "optional IANA timezone for local HH:mm strings (auto-filled from city)",
      "examples": [
        "https://theshia.org/api/v1/prayer-times?city=london&method=Tehran&year=2026&month=7",
        "https://theshia.org/api/v1/prayer-times?lat=32&lng=44.02&method=all&date=2026-07-18",
        "https://theshia.org/api/v1/prayer-times?city=tehran&method=custom&fajrAngle=17.7&ishaAngle=14&maghribAngle=4.5&year=2026"
      ]
    },
    "methods": {
      "url": "https://theshia.org/api/v1/methods"
    },
    "qibla": {
      "url": "https://theshia.org/api/v1/qibla?lat=51.51&lng=-0.13"
    },
    "cities": {
      "url": "https://theshia.org/api/v1/cities?q=london",
      "note": "search 325 curated cities by name in en/ar/fa/ur"
    },
    "hijri": {
      "url": "https://theshia.org/api/v1/hijri",
      "note": "Hijri ⇄ Gregorian, both directions — announced sightings where recorded, crescent-visibility computation (Tehran reference) everywhere else; source-tagged per answer",
      "forward": "date=YYYY-MM-DD (default today) | year&month | year — optional calendar=moonsighting|iran, offset=-2..2",
      "reverse": "hy&hm[&hd] — a Hijri date (or whole Hijri month map) to Gregorian",
      "examples": [
        "https://theshia.org/api/v1/hijri?date=2026-07-18",
        "https://theshia.org/api/v1/hijri?year=2026&month=7&calendar=iran",
        "https://theshia.org/api/v1/hijri?hy=1448&hm=1"
      ]
    },
    "events": {
      "url": "https://theshia.org/api/v1/events",
      "note": "Curated Islamic events (73, Shia dates, en/ar/fa/ur titles with honorifics) — Hijri-recurring; resolve with hy=<year> or upcoming=N",
      "params": "hm=1..12 | hy=1317..1523 [&hm] | upcoming=1..73 · filters: importance=major, type=..., details=1 · calendar=moonsighting|iran",
      "examples": [
        "https://theshia.org/api/v1/events?upcoming=5&importance=major",
        "https://theshia.org/api/v1/events?hy=1448&hm=1"
      ]
    },
    "eclipses": {
      "url": "https://theshia.org/api/v1/eclipses",
      "note": "Solar & lunar eclipses 2020-2040 (Meeus engine, NASA-verified): type, maximum UTC, gamma, magnitudes, lunar durations, greatest points, Hijri dates",
      "params": "kind=solar|lunar · type=total|annular|hybrid|partial|penumbral · from=YYYY[-MM-DD] & to= · upcoming=1..24 · calendar=moonsighting|iran",
      "examples": [
        "https://theshia.org/api/v1/eclipses?upcoming=4",
        "https://theshia.org/api/v1/eclipses?kind=solar&from=2026&to=2028"
      ]
    },
    "events.ics": {
      "url": "https://theshia.org/api/v1/events.ics",
      "note": "Subscribe in Google/Apple Calendar (webcal): Islamic events, always current — lang=en|ar|fa|ur, importance=major, calendar="
    },
    "fasting.ics": {
      "url": "https://theshia.org/api/v1/fasting.ics",
      "note": "Subscribe: recommended fasting days (Ayyam al-Bid + the emphasized fasts) — lang=, calendar="
    },
    "night.ics": {
      "url": "https://theshia.org/api/v1/night.ics?city=london",
      "note": "Subscribe: Salat al-Layl wake-up — a timed event at the last third of every night — city= required, method=, lang=, days=7..90"
    },
    "day-status": {
      "url": "https://theshia.org/api/v1/day-status",
      "note": "Today (or ?date=YYYY-MM-DD) as flags: hijri date, events, mourning/season, eid, fasting, night-of-worship — theme your masjid site with one request",
      "examples": [
        "https://theshia.org/api/v1/day-status",
        "https://theshia.org/api/v1/day-status?date=2026-08-24&calendar=iran"
      ]
    },
    "prayer-times.ics": {
      "url": "https://theshia.org/api/v1/prayer-times.ics?city=london",
      "note": "Subscribe: the five daily prayers for a city, rolling 60 days — city= required, method=, lang=, days=7..90"
    },
    "moon-visibility": {
      "url": "https://theshia.org/api/v1/moon-visibility",
      "note": "Crescent visibility (Yallop/Shaukat, AL-Qamar calibration) for a Hijri month's sighting window — the same data as theshia.org/moonsighting",
      "grid": "hy&hm (default: current month) [&evening=-2..2] [&res=5|2] — world zone grid, rows of digits 0 (not visible) .. 4 (telescope)",
      "point": "lat&lng or city=<id> [&hy&hm] — per-evening q-value + zone for the 7 evenings from conjunction, with first-visible dates per criterion",
      "examples": [
        "https://theshia.org/api/v1/moon-visibility?hy=1448&hm=2",
        "https://theshia.org/api/v1/moon-visibility?hy=1448&hm=2&evening=-1&res=2",
        "https://theshia.org/api/v1/moon-visibility?city=london&hy=1448&hm=2"
      ]
    }
  },
  "terms": "Free for community use. Cached heavily; please cache on your side too. No uptime guarantee.",
  "openapi": "https://theshia.org/api/v1/openapi.json",
  "source": "https://theshia.org"
}