Islamic events

The curated calendar of the Ahlul Bayt (a) — 73 events with Shia dates and four-language titles, resolvable to any year or queried as what's-coming-up.

GET https://theshia.org/api/v1/events

Parameters

hm optional Hijri month 1 to 12 — list that month's events.
hy optional Hijri year 1317 to 1523 — resolve every event to its Gregorian date in that year (combinable with hm).
upcoming optional 1 to 73 — the next N occurrences from today, each with gregorian date and daysUntil.
importance optional value: "major" — only the headline events (Ashura, Arbaeen, Eids, the Masumin…).
type optional values: "occasion" · "birth" · "martyrdom" · "death" · "holy".
details optional value: "1" — include the detail paragraphs (en/ar/fa; 44 events have them).
calendar default: moonsighting values: "moonsighting" · "iran" — the reckoning used to resolve dates.

73 curated events (Shia dates), titles in en/ar/fa/ur with honorifics. Events recur on their Hijri month/day; a day-30 event resolves to null in years where its month has 29 days.
Response per event: id, hijriMonth, hijriDay, type, importance, title { en, ar, fa, ur } (+ hijriYear, gregorian, daysUntil/source in resolved modes).

Open live example ↗

Code samples

curl

curl "https://theshia.org/api/v1/events?upcoming=5&importance=major"

JavaScript

const res = await fetch("https://theshia.org/api/v1/events?upcoming=5&importance=major");
const data = await res.json();

Python

import requests

data = requests.get("https://theshia.org/api/v1/events?upcoming=5&importance=major").json()

Rate limits & fair use

Responses are cached hard at the edge — please cache on your side too. Uncached requests are limited to 100 per minute per IP; oversized requests (over 496 day×method computations) are rejected. Free for community use, no uptime guarantee.