Calendar feeds (ICS)

Subscribe once in Google or Apple Calendar: every Islamic date, or a city's daily prayer times — always current, no app needed.

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

Parameters

lang default: en feed language — values: "en" · "ar" · "fa" · "ur".
importance optional value: "major" — a lighter feed with only the headline events.
calendar default: moonsighting values: "moonsighting" · "iran".
city prayer/night feeds REQUIRED for /prayer-times.ics and /night.ics — a city id from /cities.
method prayer/night feeds calculation method id (default Tehran).
days prayer/night feeds rolling window, 7 to 90 (default 60).
offsets prayer feed masjid-kit jamaat offsets, e.g. "fajr:10,maghrib:5" — minutes after the calculated time, -60 to 180.
name prayer feed masjid display name for the calendar title and event summaries (max 60 characters).

Four feeds: GET /api/v1/events.ics (Islamic events as all-day entries, ~14 months around today), GET /api/v1/prayer-times.ics?city=<id> (the five daily prayers, timed — with optional jamaat offsets and masjid name), GET /api/v1/fasting.ics (recommended fasting days — Ayyam al-Bid and the emphasized fasts), and GET /api/v1/night.ics?city=<id> (Salat al-Layl: one event at the last third of every night).
Subscribe via webcal:// (Apple, most clients) or paste the https URL into Google Calendar → “From URL”. Feeds refresh daily (X-PUBLISHED-TTL P1D) and stay current with announced sightings.

Open live example ↗

Code samples

curl

curl "https://theshia.org/api/v1/events.ics?lang=en&importance=major"

JavaScript

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

Python

import requests

data = requests.get("https://theshia.org/api/v1/events.ics?lang=en&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.