GET /events

Mengembalikan tanggal hari penting Islam dalam satu tahun.

Secara bawaan, endpoint ini mengembalikan 5 hari besar nasional: 1 Muharam, Maulid Nabi, Awal Ramadan, Idul Fitri, Idul Adha. Tambahkan parameter include untuk membuka set tambahan: Isra Mi’raj, Nuzulul Quran, Arafah, Tasu’a, Asyura, Tasyrik, serta rangkaian puasa Ayyamul Bidh. Anda bisa memilih slug satu per satu, atau semuanya.

Untuk tanggal yang tersedia di tabel MABIMS, API menggunakan data publik dari Kementerian Agama. Data ini sama dengan yang digunakan oleh endpoint /convert.

Untuk tanggal di luar tabel, API menghitung tanggal berdasarkan kriteria Neo MABIMS (lihat kriterianya). Perhitungan ini memakai ketinggian hilal minimal 3° dan elongasi minimal 6,4° saat matahari terbenam di lokasi pengamatan pesisir di Indonesia.

Dengan begitu, Anda dapat memperoleh perkiraan tanggal hari penting Islam untuk tahun-tahun mendatang.

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

Parameter

Parameter	Tipe	Wajib	Deskripsi
`year`	integer	ya	Tahun pada kalender yang dipilih (`1446` untuk Hijriah atau `2025` untuk Masehi)
`calendar`	string	tidak (bawaan `hijri`)	Pilih `gregorian` atau `hijri`
`include`	CSV	tidak	Isi `extra` untuk mendapatkan semua hari tambahan selain Ayyamul Bidh. Jika ingin memilih (tidak semua), gunakan koma untuk memisahkan: `ayyamul_bidh`, `isra_miraj`, `nuzulul_quran`, `arafah`, `tasua`, `asyura`, `tasyrik`, atau `all`. 5 hari besar bawaan selalu disertakan
`retro`	`true` / `false`	tidak (bawaan `false`)	Mengaktifkan tanggal hasil perhitungan untuk tahun sebelum tabel tersedia, sampai 1 Januari 1945. Data ini diberi tanda `mabims-retro`. Lihat cakupan data

Contoh

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;
}

Respons

{
  "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": []
}

Item diurutkan berdasarkan tanggal Masehi.

Hari yang tersedia

`event`	Nama	Bulan Hijriah	Tanggal	Set
`1_muharram`	Tahun Baru Islam	1 (Muharam)	1	bawaan
`maulid_nabi`	Maulid Nabi Muhammad	3 (Rabiulawal)	12	bawaan
`awal_ramadan`	Awal Ramadan	9 (Ramadan)	1	bawaan
`idul_fitri`	Idulfitri	10 (Syawal)	1	bawaan
`idul_adha`	Idul Adha	12 (Zulhijah)	10	bawaan
`isra_miraj`	Isra Mi’raj	7 (Rajab)	27	`extra`
`nuzulul_quran`	Nuzulul Quran	9 (Ramadan)	17	`extra`
`arafah`	Puasa Arafah	12 (Zulhijah)	9	`extra`
`tasua`	Puasa Tasu’a	1 (Muharam)	9	`extra`
`asyura`	Puasa Asyura	1 (Muharam)	10	`extra`
`tasyrik`	Hari Tasyrik	12 (Zulhijah)	11–13	`extra`
`ayyamul_bidh`	Puasa Ayyamul Bidh	semua bulan 1–12	13–15 (14–16 di Dzulhijjah *)	`ayyamul_bidh`

* 13 adalah hari Tasyrik ke-3 (diamalkan haram puasa), jadi ayyamul bidh Dzulhijjah bergeser ke 14–16.

Contoh kombinasi `include`

# 5 hari besar saja (bawaan)
curl "https://api.mabims.dev/api/v1/events?year=2025&calendar=gregorian"

# + hari tambahan: Isra Mi'raj, Nuzulul Quran, Arafah, Tasu'a, Asyura, Tasyrik
curl "https://api.mabims.dev/api/v1/events?year=2025&calendar=gregorian&include=extra"

# 5 hari besar + Ayyamul Bidh (13-15 setiap bulan; 14-16 di Dzulhijjah)
curl "https://api.mabims.dev/api/v1/events?year=2025&calendar=gregorian&include=ayyamul_bidh"

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

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

Catatan

Jika tanggal berasal dari tabel, nilai source adalah mabims.
Jika tanggal dihitung di luar tabel, nilai source adalah mabims-computed.
Jika API memakai hasil perhitungan, penjelasannya dicantumkan dalam warnings[].
Saat memakai calendar=gregorian, API mencari tahun Hijriah yang beririsan dengan tahun Masehi yang diminta, lalu mengembalikan setiap hari penting yang termasuk di dalamnya.
Seperti /convert, hasil yang berasal dari tabel disimpan di CDN dan tidak berubah.
Event multi-hari (tasyrik, ayyamul_bidh) punya field date_range tambahan yang berisi hijri_start, hijri_end, gregorian_start, gregorian_end. Event satu hari punya date_range: null.
include yang Anda kirim digema kembali di input.include (atau null bila tidak diisi) supaya klien bisa memverifikasi set yang aktif.

Kesalahan

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

`code`	HTTP	Penyebab
`invalid_calendar`	400	Nilai `calendar` bukan `gregorian` atau `hijri`
`invalid_include`	400	Nilai `include` bukan `extra`, `ayyamul_bidh`, `all`, atau slug yang valid
`invalid_year`	400	Tahun di luar batas yang didukung
`invalid_retro`	400	Parameter `retro` bukan nilai boolean (menerima `true`/`false`, `1`/`0`)

Flag boolean menerima true/false (tidak peka huruf besar/kecil) dan 1/0; tanpa param = false.