Hijri date conversion

Convert dates both ways between the Hijri and Gregorian calendars — a single day, a whole month, or a year per request, under the global moonsighting reckoning or Iran's official calendar. Announced sighted months come from curated tables; beyond them the crescent's actual visibility is computed astronomically, and every answer names its source.

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

Parameters

date default: today Gregorian day to convert, YYYY-MM-DD (years 1900 to 2100).
year optional with month: that Gregorian month as a day-by-day map; alone: the full year (366-day budget).
month optional 1 to 12, combined with year.
hy reverse Hijri year, 1317 to 1523 (≈ Gregorian 1900–2100) — switches the direction to Hijri → Gregorian.
hm reverse Hijri month, 1 (Muharram) to 12 (Dhul Hijjah).
hd reverse Hijri day, 1 to that month's real length (checked); omit it for the whole month as a day-by-day map.
calendar default: moonsighting values: "moonsighting" (global crescent sighting) · "iran" (official reckoning; outside its table — after 19 March 2028 — it answers as moonsighting and says so in calendarUsed).
offset default: 0 -2 to 2 whole days — the conventional local-sighting adjustment, applied before Gregorian → Hijri conversion only.

Answer layers, reported in source: "table" (an announced sighting, or Iran's official reckoning) → "computed" (crescent-visibility calculation: Meeus new moon + Yallop/Shaukat criterion, Tehran reference — the same engine as AL-Qamar; covers all future and historic dates) → "tabular" (arithmetic estimate, last resort).
Response: gregorian, weekday, hijri { year, month, day }, monthName { en, ar, fa, ur }, formatted { en, ar, fa, ur } with localized digits, monthLength, calendarUsed, source. Whole-month Hijri queries return gregorianStart, gregorianEnd and a days map instead.
Identical to the Hijri date shown on this site — both run the same library.

Open live example ↗

Code samples

curl

curl "https://theshia.org/api/v1/hijri?hy=1448&hm=1"

JavaScript

const res = await fetch("https://theshia.org/api/v1/hijri?hy=1448&hm=1");
const data = await res.json();

Python

import requests

data = requests.get("https://theshia.org/api/v1/hijri?hy=1448&hm=1").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.