GET /events

Returns the Islamic observance dates for one calendar year. Within the curated MABIMS table, dates come straight from the public 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 local sunset, evaluated at coastal observation points across Indonesia), giving you observance dates years into the future.

By default the endpoint returns the 5 base events (Islamic New Year, Maulid, Ramadan start, Eid al-Fitr, Eid al-Adha), so existing clients get exactly the responses they got before. Add the include parameter to unlock the tier-2 observances (Isra’ and Mi’raj, Nuzulul Quran, Arafah, Tasu’a, Ashura, Tasyrik), the Ayyamul Bidh fasting days, individually cherry-picked slugs, or everything at once.

GET/api/v1/events?year={Y}&calendar={gregorian|hijri}&include={extra|ayyamul_bidh|all|slug,...}&retro={true|false}

Parameters

Parameter	Type	Required	Description
`year`	integer	yes	Year in the requested `calendar` (Hijri: `1446`, Gregorian: `2025`)
`calendar`	string	no (default `hijri`)	`gregorian` or `hijri`
`include`	CSV	no	Comma-separated: `extra` (all of tier 2), `ayyamul_bidh`, individual slugs (`isra_miraj`, `nuzulul_quran`, `arafah`, `tasua`, `asyura`, `tasyrik`), or `all`. The 5 base events are always included and cannot be removed
`retro`	`true` / `false`	no (default `false`)	Unlocks computed retro dates below the curated table (down to 1945-01-01), tagged `mabims-retro`. See data coverage for the reason why

`include` combinations

# base 5 only (default)
curl "https://api.mabims.dev/api/v1/events?year=2025&calendar=gregorian"

# + tier-2 observances (Isra' and Mi'raj, Nuzulul Quran, Arafah, Tasu'a, Ashura, Tasyrik)
curl "https://api.mabims.dev/api/v1/events?year=2025&calendar=gregorian&include=extra"

# base 5 + Ayyamul Bidh (13-15 every month; 14-16 in Dhul Hijjah)
curl "https://api.mabims.dev/api/v1/events?year=2025&calendar=gregorian&include=ayyamul_bidh"

# cherry-pick
curl "https://api.mabims.dev/api/v1/events?year=2025&calendar=gregorian&include=asyura,arafah"

# everything
curl "https://api.mabims.dev/api/v1/events?year=2025&calendar=gregorian&include=all"

Example

curl "https://api.mabims.dev/api/v1/events?year=1446&calendar=hijri"

const res = await fetch("https://api.mabims.dev/api/v1/events?year=1446&calendar=hijri");
const data = await res.json();
data.events.forEach(e => console.log(e.name, e.gregorian));

$response = GuzzleHttp\request('GET', 'https://api.mabims.dev/api/v1/events?year=1446&calendar=hijri');
$data = json_decode($response->getBody(), true);
foreach ($data['events'] as $event) {
    echo $event['name'] . ' ' . $event['gregorian'] . PHP_EOL;
}

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	Set
`1_muharram`	Islamic New Year	1 (Muharram)	1	default
`maulid_nabi`	Prophet’s Birthday	3 (Rabi’ al-awwal)	12	default
`awal_ramadan`	First day of Ramadan	9 (Ramadan)	1	default
`idul_fitri`	Eid al-Fitr	10 (Shawwal)	1	default
`idul_adha`	Eid al-Adha	12 (Dhu al-Hijjah)	10	default
`isra_miraj`	Isra’ and Mi’raj	7 (Rajab)	27	`extra`
`nuzulul_quran`	Nuzulul Quran	9 (Ramadan)	17	`extra`
`arafah`	Arafah fasting	12 (Dhu al-Hijjah)	9	`extra`
`tasua`	Tasu’a fasting	1 (Muharram)	9	`extra`
`asyura`	Ashura fasting	1 (Muharram)	10	`extra`
`tasyrik`	Days of Tashriq	12 (Dhu al-Hijjah)	11–13	`extra`
`ayyamul_bidh`	Ayyamul Bidh fasting	every month 1–12	13–15 (14–16 in Dhul Hijjah *)	`ayyamul_bidh`

* Day 13 is the third Tashriq day (fasting is forbidden there), so the white days in Dhul Hijjah shift to 14–16.

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.
Multi-day events (tasyrik, ayyamul_bidh) carry an extra date_range field with hijri_start, hijri_end, gregorian_start, gregorian_end. Single-day events have date_range: null.
The include value you send is echoed back in input.include (or null when unset) so clients can verify which set is active.

Errors

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

`code`	HTTP	Cause
`invalid_calendar`	400	Calendar is not `gregorian` or `hijri`
`invalid_include`	400	`include` value is not `extra`, `ayyamul_bidh`, `all`, or a valid slug
`invalid_year`	400	Year out of supported bounds
`invalid_retro`	400	`retro` param is not a boolean value (accepts `true`/`false`, `1`/`0`)

Boolean flags accept true/false (case-insensitive) and 1/0; absent = false.