GET /events

Returns the Islamic observance dates for one calendar year. Within the curated MABIMS table, dates come straight from the official Kemenag table — the same one that powers /convert. Beyond table coverage, dates are computed live using the Neo MABIMS criteria (hilal altitude ≥ 3° and elongation ≥ 6.4° at Sabang sunset), giving you observance dates years into the future.

GET /api/v1/events?year={Y}&calendar={gregorian|hijri}

Parameters

Parameter	Type	Required	Description
year	integer	yes	Year in the requested calendar (Hijri: 1446, Gregorian: 2025)
calendar	string	no (default gregorian)	gregorian or hijri

Response

{
  "input": { "year": 1446, "calendar": "hijri" },
  "count": 5,
  "events": [
    { "event": "1_muharram",   "name": "Tahun Baru Islam",         "hijri": "1446-01-01", "gregorian": "2024-07-07", "source": "mabims" },
    { "event": "maulid_nabi",  "name": "Maulid Nabi Muhammad Shallallahu Alaihi Wasallam", "hijri": "1446-03-12", "gregorian": "2024-09-16", "source": "mabims" },
    { "event": "awal_ramadan", "name": "Awal Ramadan",             "hijri": "1446-09-01", "gregorian": "2025-03-01", "source": "mabims" },
    { "event": "idul_fitri",   "name": "Idul Fitri",               "hijri": "1446-10-01", "gregorian": "2025-03-31", "source": "mabims" },
    { "event": "idul_adha",    "name": "Idul Adha",                "hijri": "1446-12-10", "gregorian": "2025-06-06", "source": "mabims" }
  ],
  "warnings": []
}

Items are sorted by Gregorian date.

Available events

event	Name	Hijri month	Day
1_muharram	Islamic New Year	1 (Muharram)	1
maulid_nabi	Prophet’s Birthday	3 (Rabi’ al-awwal)	12
awal_ramadan	First day of Ramadan	9 (Ramadan)	1
idul_fitri	Eid al-Fitr	10 (Shawwal)	1
idul_adha	Eid al-Adha	12 (Dhu al-Hijjah)	10

Notes

• Within table coverage, source is mabims. Beyond it, source is mabims-computed (Neo MABIMS criteria).
• Warnings are included when computed data is used — check the warnings[] array in the response.
• For calendar=gregorian, the endpoint estimates which hijri years overlap the requested gregorian year and resolves each event across those years.
• Like /convert, responses within table coverage are cached immutably at the CDN.

Errors

{
  "error": {
    "code": "invalid_year",
    "message": "..."
  }
}

code	HTTP	Cause
invalid_calendar	400	Calendar is not gregorian or hijri
invalid_year	400	Year out of supported bounds