GET /hilal

MABIMS API menyediakan empat endpoint untuk visibilitas hilal. Malam yang diperiksa selalu malam ke-29 bulan Hijriah yang sedang berjalan, yaitu malam saat hilal diamati. Jika kriteria tidak terpenuhi di satu pun titik pengamatan, bulan tersebut menjadi 30 hari dan awal bulan berikutnya bergeser satu hari. Penentuan awal bulan menggunakan data publik resmi dari Kementerian Agama RI. Data astronominya dihitung dengan model multi-titik: kriteria diperiksa di titik pengamatan pesisir di seluruh Indonesia. Saat ini ada 25 titik, dari Sabang sampai Rote. Daftar lengkapnya tersedia di api/data/hilal_sites.json.

GET /api/v1/hilal/info?month={bulan}&year={tahun}   → JSON
GET /api/v1/hilal/viz?month={bulan}&year={tahun}    → PNG 720×1280
GET /api/v1/hilal/map?month={bulan}&year={tahun}    → PNG 720×1280
GET /api/v1/hilal/history?from={YYYY-MM}&to={YYYY-MM} → JSON (riwayat)

info mengembalikan angka perhitungan dan hasilnya; viz membuat grafik langit yang menunjukkan kondisi hilal; map membuat peta wilayah visibilitas di seluruh Nusantara. Semua endpoint ini dapat diakses secara publik, tetapi memiliki batas permintaan yang lebih ketat: info 60 permintaan per jam, sedangkan viz dan map masing-masing 30 permintaan per jam untuk setiap IP.

Parameter

Parameter	Tipe	Wajib	Deskripsi
`month`	int 1–12	ya	Bulan Hijriah target. Grafik menampilkan malam penentuan awal bulan tersebut.
`year`	int	ya	Tahun Hijriah target.
`retro`	`true` / `false`	tidak (bawaan `false`)	Mengaktifkan tanggal hasil perhitungan sebelum tabel tersedia, sampai 1 Januari 1945, dengan label `mabims-retro`. Lihat cakupan data
`bare`	`true` / `false`	tidak (bawaan `false`)	Hanya untuk `viz` dan `map`: menghapus panel kriteria dan mengembalikan kartu resolusi tinggi 1440×1520 (header, grafik, dan logo) untuk digunakan sebagai gambar utama di web.
`download`	`true` / `false`	tidak (bawaan `false`)	Hanya untuk `viz` dan `map`: mengirim `Content-Disposition: attachment` agar browser mengunduh PNG, bukan membukanya. Berguna karena atribut `download` HTML tidak berlaku untuk URL lintas origin.

Model yang digunakan adalah “terlihat di mana saja di Indonesia”. Kriteria Neo MABIMS diperiksa saat matahari terbenam di setiap titik pengamatan, sama seperti pada perhitungan tabel. Jika kriteria terpenuhi, respons melaporkan titik penentu melalui deciding_site.

Contoh

curl "https://api.mabims.dev/api/v1/hilal/info?month=11&year=1447"

const res = await fetch("https://api.mabims.dev/api/v1/hilal/info?month=11&year=1447");
const data = await res.json();
console.log("Visible:", data.evening.visible, "at", data.evening.deciding_site?.name);

$response = GuzzleHttp\request('GET', 'https://api.mabims.dev/api/v1/hilal/info?month=11&year=1447');
$data = json_decode($response->getBody(), true);
echo 'Visible: ' . ($data['evening']['visible'] ? 'true' : 'false') . PHP_EOL;

{
  "input": { "month": 11, "year": 1447 },
  "month": { "name": "Dzulqa'dah", "number": 11, "year": 1447, "start": "2026-04-19" },
  "previous_month": { "name": "Syawal", "number": 10, "year": 1447, "length": 29 },
  "evening": {
    "hijri_date": "29 Syawal 1447 H",
    "hijri_day": 29,
    "gregorian_date": "2026-04-18",
    "sunset": "18:46",
    "moonset": "19:31",
    "moon_alt_deg": 10.36,
    "moon_az_deg": 289.16,
    "sun_alt_deg": -0.83,
    "elongation_deg": 14.52,
    "illumination_pct": 1.44,
    "age_hours": 23.9,
    "deciding_site": {
      "name": "Sabang / Weh Island",
      "lat": 5.8897,
      "lon": 95.3164,
      "elev_m": 16.0,
      "tz": "Asia/Jakarta"
    },
    "sites_checked": 25,
    "alt_ok": true,
    "elong_ok": true,
    "visible": true
  },
  "source": "mabims",
  "warnings": []
}

Kriteria keterlihatan

Kolom visible bernilai true jika kriteria terpenuhi di setidaknya satu titik pengamatan:

Ketinggian Bulan ≥ 3,0°: dihitung secara toposentris, yaitu berdasarkan posisi hilal relatif terhadap pengamat, dan sudah dikoreksi dengan refraksi atmosfer menggunakan formula Bennett;
Elongasi ≥ 6,4°: dihitung secara geosentris sesuai konvensi hisab Indonesia, yaitu jarak sudut antara Bulan dan Matahari.

(Lihat penjelasan resmi dari MUI dan pengumuman pemerintah di Setkab tentang kriteria ini.)

Kedua nilai tersebut dievaluasi saat matahari terbenam di titik pengamatan masing-masing pada hari ke-29. Semakin ke barat lokasi pengamatan, semakin tinggi posisi hilal saat matahari terbenam. Karena itu, bulan-bulan dengan kondisi yang cukup aman biasanya ditentukan di pesisir barat, terutama Aceh. Namun, ketika deklinasi Bulan berada di selatan, titik-titik di jalur selatan, dari Jawa sampai Nusa Tenggara, dapat menjadi penentu.

Kolom deciding_site selalu terisi. Jika kriteria tidak terpenuhi di titik mana pun, kolom ini berisi titik dengan margin terbaik, yaitu titik yang paling mendekati batas kriteria. Semua nilai ketinggian, elongasi, dan waktu pada respons merujuk pada titik tersebut.

Waktu matahari terbenam dan Bulan terbenam, azimut, iluminasi, serta umur Bulan dihitung secara toposentris di titik penentu, bukan selalu di Sabang. Waktu ditampilkan dalam zona waktu lokal titik tersebut, yaitu WIB atau WITA.

Grafik (`/hilal/viz`)

Endpoint ini mengembalikan PNG vertikal berukuran 720×1280 yang berisi langit senja dengan bulan sabit, dengan sisi terang menghadap Matahari. Gambar juga memuat label status (MEMENUHI KRITERIA, TIDAK MEMENUHI, MENDEKATI BATAS, atau DI BAWAH HORIZON); serta tabel kriteria PARAMETER · MIN. MABIMS · STATUS dan baris TITIK PENGAMAT.

Adegan langit, angka kriteria, dan waktu di dalam grafik semuanya merujuk pada titik penentu yang sama. Untuk parameter yang sama, output yang dihasilkan selalu konsisten.

Contoh grafik visibilitas hilal, 29 Syawal 1447 H, ditentukan di Sabang

Peta (`/hilal/map`)

Endpoint ini mengembalikan PNG 720×1280 berisi peta wilayah keterlihatan seluruh Nusantara: area tempat kriteria Neo MABIMS terpenuhi saat matahari terbenam, garis batas ketinggian 3° dan elongasi 6,4°, serta 95 titik tampilan (hijau = memenuhi, abu-abu = tidak memenuhi). Titik penentu dari model 25 titik ditandai dengan cincin kuning.

Tabel pada kartu memakai angka titik penentu yang sama dengan /hilal/viz, ditambah rekap TITIK MEMENUHI dan TITIK TIDAK MEMENUHI dari 95 titik. Dengan begitu kedua kartu selalu menyebut titik pengamat yang sama. Rate limit: 30 permintaan per jam per IP.

Contoh peta wilayah visibilitas hilal, 29 Syawal 1447 H

Riwayat (`/hilal/history`)

/hilal/history mengembalikan ringkasan setiap bulan untuk rentang Hijriah from–to (format YYYY-MM, bawaan seluruh indeks 1444-08 → 1475-12). Datanya diambil dari indeks api/data/hilal_index.json, sehingga satu permintaan cukup untuk menampilkan seluruh daftar riwayat tanpa memanggil /hilal/info berkali-kali. Setiap entri memiliki bentuk yang sama dengan /hilal/info (bulan target, bulan sebelumnya, evening, source, warnings).

{
  "input": { "from": "1444-08", "to": "1475-12" },
  "count": 377,
  "range": { "first": "1444-08", "last": "1475-12" },
  "months": [
    {
      "month": { "name": "Sya'ban", "number": 8, "year": 1444, "start": "2023-02-22" },
      "previous_month": { "name": "Rajab", "number": 7, "year": 1444, "length": 30 },
      "evening": { "hijri_date": "29 Rajab 1444 H", "gregorian_date": "2023-02-20", "visible": false, "moon_alt_deg": 2.32, "elongation_deg": 5.26, "deciding_site": { "name": "Lhoknga / Tgk. Chiek Kuta Karang" } },
      "source": "mabims",
      "warnings": []
    }
  ],
  "warnings": []
}

Indeks dibuat dengan python -m scripts.generate_hilal_index. Buat ulang setelah kriteria, daftar titik, atau ephemeris berubah, atau setelah tabel Kemenag diperluas.

Penyimpanan di cache

Cache-Control: public, max-age=86400, s-maxage=86400: hasilnya selalu sama untuk parameter yang sama dan disimpan di CDN. CDN membuat satu gambar per lokasi edge setiap hari.
Proses pembuatan gambar menggunakan CPU. Gunakan parameter seperlunya dan patuhi batas permintaan.
Batas gambar: Hijriah 1444–1475: kartu PNG hanya tersedia dalam rentang itu (lihat hilal_image_range di /meta). Di luar rentang tersebut, endpoint mengembalikan out_of_coverage. Cakupan data tanggal tetap tercantum di coverage.forward_ceil.

Setiap respons juga menyertakan ETag. Kirim If-None-Match: <etag> dan server menjawab 304 Not Modified (tanpa body) bila data belum berubah, dengan Cache-Control dan ETag yang sama.

Kesalahan

Kode	HTTP	Penyebab
`out_of_coverage`	400	Bulan atau tahun berada di luar cakupan tabel (lihat `/meta`).
`computation_unavailable`	503	Perhitungan astronomi gagal.
`render_failed`	500	Gagal merender PNG.
`invalid_retro`	400	Parameter `retro` bukan nilai boolean (menerima `true`/`false`, `1`/`0`).
`invalid_bare`	400	`bare` bukan nilai boolean (menerima `true`/`false`, `1`/`0`)
`invalid_download`	400	`download` bukan nilai boolean (menerima `true`/`false`, `1`/`0`)
`rate_limit_exceeded`	429	Terlalu banyak permintaan; tunggu sesuai header `Retry-After` (detik)
`not_found`	404	Path tidak dikenal (respons error seragam)

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