API Kalender MABIMS | Blog

Kenapa Cari Hilal di Sabang?

Sat, 29 Aug 2026 00:00:00 GMT

Salah satu endpoint yang paling saya suka di mabims.dev bukan /today atau /convert, tapi /hilal/viz. Endpoint ini generate PNG 720×1280 yang nampilin visualisasi langit senja lengkap dengan posisi bulan, status kelolosan kriteria MABIMS, sampai grafik langit dengan bintang-bintang segala.

Nggak ada API kalender Hijriah lain (setidaknya yang saya temukan) yang punya fitur ini. Jadi tulisan ini bahas gimana cara kerjanya, dari astronomi sampai render pixel.

Kenapa Sabang?

Ini pertanyaan yang paling sering saya dapat. Jawabannya simpel: Sabang adalah titik paling barat Indonesia.

Untuk urusan rukyah (pengamatan hilal), posisi geografis penting, karena semakin barat, maka matahari terbenam semakin mundur. Artinya, kalau hilal tidak memenuhi kriteria di tempat lain, last chance nya akan terjadi di Sabang.

Ini bukan aturan resmi MABIMS soal “wajib pakai Sabang”, tapi jadi titik acuan praktis yang masuk akal untuk representasi visibilitas hilal se-Indonesia dalam satu titik koordinat.

Alur Kerjanya

Simplifikasi dari implementasi aslinya kira-kira begini:

FUNCTION hilal_viz(month, year):
  sighting = resolve_sighting_evening(year, month)
  observation = observe_sighting_evening(sighting.evening_date)
  alt_ok = observation.moon_alt >= 3.0°
  elong_ok = observation.elongation >= 6.4°
  data = build_chart_data(...)
  img = render_chart(data)
  return PNG

1. Resolve malam pengamatan

Kalau kamu minta visibilitas untuk bulan Ramadhan, endpoint ini nggak menghitung tanggal 1 Ramadhan itu sendiri, tapi mundur ke malam ke-29 Sya’ban, karena itu malam yang sebenarnya diamati untuk menentukan apakah besok sudah masuk Ramadhan atau belum. Ini logika dasar rukyah: kamu mengamati hilal di ujung bulan berjalan, bukan di awal bulan target.

2. Hitung astronomi malam itu, dari Sabang

Dua kategori data dihitung:

Kriteria geosentrik — moon_alt (altitude/ketinggian bulan), moon_az (azimuth), sun_alt, dan elongation (jarak sudut bulan-matahari). Ini angka-angka yang langsung dibandingkan ke ambang batas MABIMS.
Waktu pengamat (observer-clock) — iluminasi, jam matahari terbenam lokal, dan jam bulan terbenam. Ini yang ditampilkan sebagai info tambahan di kartu bawah.

3. Cek ambang batas Neo MABIMS

alt_ok  = moon_alt   >= 3.0°
elong_ok = elongation >= 6.4°

Dua syarat ini harus terpenuhi bersamaan. Kalau salah satu gagal, hilal dianggap belum memenuhi kriteria visibilitas, meskipun bulan sudah di atas horizon.

Contoh Hasil

Screenshot di atas itu visibilitas untuk 1 Muharram 1448 H (evaluasi malam 29 Dzulhijjah 1447 H, 15 Jun 2026, dari Sabang):

Altitude bulan +5.0° (lolos, syarat ≥3.0°)
Elongasi 7.0° (lolos, syarat ≥6.4°)
Iluminasi 0.2% — sangat tipis, hilal masih sangat muda
Matahari terbenam 18:53, bulan terbenam 19:11, cuma selisih 18 menit

Status: TERLIHAT, meski dengan margin yang nggak terlalu lebar.

Kenapa Repot-repot Bikin Ini?

Karena angka mentah (moon_alt: 5.2, elongation: 8.7) nggak intuitif buat kebanyakan orang, termasuk saya sendiri. Tapi begitu divisualisasikan -> lihat posisi bulan relatif ke horizon, lihat pill hijau/merah, lihat tabel kriteria -> jadi jauh lebih gampang dicerna. Endpoint ini niatnya bukan cuma buat developer yang butuh JSON, tapi juga buat siapa saja yang penasaran “kok bisa sih hilal dibilang terlihat/tidak terlihat” tanpa harus paham astronomi.

Coba sendiri di playground:

GET https://api.mabims.dev/api/v1/hilal/viz?month=1&year=1448

Ganti month dan year sesuai bulan Hijriah yang mau dicek. Dokumentasi lengkap parameter ada di mabims.dev/endpoints/hilal.

Tutorial Integrasi

Fri, 28 Aug 2026 00:00:00 GMT

API ini saya bikin buat developer, dan saya nggak mau integrasinya berhenti di dokumentasi yang isinya cuma GET /today lalu selesai. Jadi di tulisan ini saya mau kasih contoh dari yang paling sederhana sampai yang agak proper: JavaScript biasa, Vue, React, sampai aplikasi mobile.

Paling sederhana: JavaScript

Kalau website kamu cuma butuh menampilkan tanggal Hijriah hari ini, sebenarnya sesimpel ini:

const response = await fetch("https://api.mabims.dev/api/v1/today");
const data = await response.json();

console.log(data);

Response-nya kira-kira begini:

{
  "input": { "date": "2026-08-28", "calendar": "gregorian", "tz": "Asia/Jakarta" },
  "output": { "date": "1448-03-15", "calendar": "hijri", "day": 15, "month": 3, "month_name": "Rabiul Akhir", "year": 1448 },
  "source": "mabims",
  "warnings": []
}

Kamu tinggal ambil field output untuk ditampilkan. Sudah lengkap, tidak perlu parse sendiri:

const { day, month_name, year } = data.output;
document.querySelector("#hijri-date").textContent = `${day} ${month_name} ${year} H`;

Jadi misalnya di header website kamu ada:

<div id="hijri-date"></div>

tinggal panggil fungsi tadi dan tanggal Hijriahnya akan muncul.

Nggak perlu install library. Nggak perlu API key. Nggak perlu bikin server sendiri cuma untuk mengambil tanggal Hijriah.

Kalau pakai timezone

Ini bagian yang menurut saya penting.

Tanggal Hijriah bukan cuma soal konversi tanggal Masehi → Hijriah. Timezone juga menentukan “hari ini” itu hari apa.

Misalnya server kamu berada di Amerika, tapi user kamu kebanyakan di Indonesia. Jangan sampai jam 00:30 WIB dianggap masih tanggal sebelumnya karena server kamu masih berada di hari sebelumnya.

mabims.dev menyediakan timezone override supaya kamu bisa menentukan timezone yang ingin digunakan. Pakai parameter tz:

const response = await fetch(
  "https://api.mabims.dev/api/v1/today?tz=Asia/Jakarta"
);

const data = await response.json();

Untuk aplikasi yang memang targetnya Indonesia, saya biasanya akan eksplisit menggunakan Asia/Jakarta, Asia/Makassar, atau Asia/Jayapura sesuai kebutuhan.

Di Vue

Kalau kamu pakai Vue, konsepnya sama. Bedanya cuma kita simpan hasil API ke state.

Misalnya dengan Composition API:

<script setup>
import { ref, onMounted } from "vue";

const hijriDate = ref(null);

onMounted(async () => {
  const response = await fetch(
    "https://api.mabims.dev/api/v1/today?tz=Asia/Jakarta"
  );

  hijriDate.value = await response.json();
});
</script>

<template>
  <div v-if="hijriDate">
    {{ hijriDate.output.date }}
  </div>

  <div v-else>
    Memuat tanggal Hijriah...
  </div>
</template>

Selesai.

Saya justru menyarankan pendekatan seperti ini daripada memasukkan library kalender Hijriah yang ukurannya jauh lebih besar kalau kebutuhan aplikasi kamu cuma menampilkan tanggal Hijriah.

Di React

Di React juga kurang lebih sama:

import { useEffect, useState } from "react";

export default function HijriDate() {
  const [date, setDate] = useState(null);

  useEffect(() => {
    fetch("https://api.mabims.dev/api/v1/today?tz=Asia/Jakarta")
      .then((response) => response.json())
      .then((data) => setDate(data));
  }, []);

  if (!date) {
    return <span>Memuat tanggal Hijriah...</span>;
  }

  return <span>{date.output.date}</span>;
}

Tidak ada dependency tambahan.

React tinggal fetch API → simpan hasilnya → render.

Kalau butuh tanggal tertentu

/today cocok kalau yang kamu butuhkan adalah tanggal Hijriah hari ini.

Tapi bagaimana kalau user memilih tanggal dari date picker?

Misalnya user memilih:

17 Agustus 2026

Kamu bisa menggunakan endpoint konversi:

const response = await fetch(
  "https://api.mabims.dev/api/v1/convert?date=2026-08-17"
);

const data = await response.json();

Ini berguna untuk kalender, form, artikel yang punya tanggal publikasi, atau fitur pencarian tanggal.

Misalnya user memilih tanggal 17 Agustus 2026 dan kamu ingin menampilkan versi Hijriahnya. Tinggal kirim tanggal Gregorian tersebut ke API.

Jangan lupa cek `source`

Ada satu hal yang menurut saya cukup penting ketika mengonsumsi API ini.

Response mabims.dev punya informasi source.

Secara sederhana, ada dua kemungkinan:

mabims — tanggal berasal dari tabel resmi Kemenag yang tersedia.
mabims-computed — tanggal dihitung menggunakan kriteria Neo MABIMS sebagai fallback ketika tanggal tersebut berada di luar cakupan tabel.

Kenapa saya expose informasi ini?

Karena saya nggak mau API diam-diam memberikan hasil perhitungan lalu developer mengira itu adalah tanggal resmi dari Kemenag.

Kalau aplikasi kamu cukup serius soal kalender, kamu bisa menyimpan atau menampilkan informasi tersebut.

if (data.source === "mabims-computed") {
  console.log("Tanggal menggunakan hasil perhitungan Neo MABIMS");
}

Dan kalau API mengembalikan warnings, sebaiknya jangan dibuang begitu saja.

if (data.warnings?.length) {
  console.warn(data.warnings);
}

Kalau aplikasinya mobile

Kalau kamu bikin aplikasi Android/iOS, prinsipnya sebenarnya sama.

Mau Flutter, React Native, Kotlin, Swift, atau framework lainnya, selama aplikasinya bisa melakukan HTTP request, kamu bisa memanggil API ini.

Misalnya pseudocode-nya:

GET https://api.mabims.dev/api/v1/today?tz=Asia/Jakarta
        ↓
JSON response
        ↓
Simpan ke state
        ↓
Tampilkan:
"1448-03-15"

API-nya tidak peduli apakah request datang dari browser, server, atau aplikasi mobile.

Tapi apakah setiap halaman harus request ke API?

Nah, ini yang mulai masuk ke urusan arsitektur.

Kalau website kamu punya 100 komponen yang semuanya membutuhkan tanggal Hijriah, jangan setiap komponen melakukan fetch("/today") sendiri-sendiri.

Lebih baik fetch sekali, kemudian hasilnya dipakai bersama.

Di frontend kamu bisa bikin composable/hook/service sendiri.

Misalnya di React:

export async function getHijriToday() {
  const response = await fetch(
    "https://api.mabims.dev/api/v1/today?tz=Asia/Jakarta"
  );

  if (!response.ok) {
    throw new Error("Gagal mengambil tanggal Hijriah");
  }

  return response.json();
}

Kemudian komponen-komponen lain tinggal menggunakan fungsi tersebut.

Untuk aplikasi yang lebih besar, bahkan bisa kamu cache hasilnya karena tanggal Hijriah tidak berubah setiap beberapa detik.

Kalau pakai SSR atau backend?

Ini malah lebih menarik.

Kalau kamu menggunakan Next.js, Nuxt, Laravel, Rails, Django, atau backend lainnya, kamu juga bisa memanggil mabims.dev dari server kamu.

Contohnya secara sederhana:

const response = await fetch(
  "https://api.mabims.dev/api/v1/today?tz=Asia/Jakarta"
);

const hijriDate = await response.json();

Kemudian server kamu yang mengirimkan tanggal tersebut ke browser.

Keuntungannya, tanggal Hijriah bisa sudah tersedia ketika halaman pertama kali dirender.

Tapi kalau kamu melakukan ini, tetap pikirkan caching. Tidak ada gunanya server kamu request tanggal yang sama berkali-kali dalam sehari.

Jadi kapan sebaiknya pakai API ini?

Menurut saya, kalau kebutuhanmu cuma:

“Saya ingin menampilkan tanggal Hijriah di website saya.”

Jangan bikin sistem kalender sendiri.

Jangan maintain tabel sendiri.

Jangan copy-paste tanggal dari kalender PDF ke database.

Dan jangan berharap library kalender yang default-nya Umm al-Qura otomatis cocok untuk kebutuhan Indonesia.

Cukup:

Website / App
      ↓
mabims.dev
      ↓
Tanggal Hijriah berbasis MABIMS

Kalau butuh tanggal hari ini, pakai /today.

Kalau butuh konversi tanggal tertentu, pakai /convert.

Kalau aplikasinya butuh timezone tertentu, tentukan timezone-nya secara eksplisit.

Dan kalau aplikasimu penting secara administratif atau keagamaan, tetap perlakukan API sebagai sumber data teknis, bukan pengganti keputusan resmi Kemenag.

Sekian. Semoga bermanfaat!

Cerita di Balik MABIMS API

Thu, 27 Aug 2026 00:00:00 GMT

Ada cerita lucu (dan sedikit menyedihkan) di balik mabims.dev.

Dulu, website Kemenag pernah menampilkan tanggal Hijriah di halamannya. Banyak orang termasuk saya sendiri terbiasa mengandalkannya. Tinggal buka website, lihat pojok atas, jadi tahu deh sekarang tanggal berapa Hijriah.

Sampai suatu hari, ada postingan viral. Kalender keluaran Kemenag bilang tanggal 30, tapi website Kemenag bilang udah masuk tanggal 1 bulan berikutnya. Selisih sehari.

Postingan itu itu nyebar. Rame. Orang-orang mempertanyakan kenapa situs resmi bisa beda sama kalendernya yang dikeluarkan sendiri.

Solusinya? Dihapus aja

Saat itu saya nggak tahu detail di baliknya, apakah itu bug, salah kalkulasi, atau apa. Yang saya tahu, ujung-ujungnya elegan sekali: tanggal Hijriah di website itu dihapus. Bukan diperbaiki, dihapus. Masalah selesai sih iya… tapi kayak gimana gitu.

Beberapa tahun kemudian, saya jadi junior dev

Waktu saya mulai kerja sebagai developer, saya baru ngerti apa yang mungkin terjadi. Kalau mau nampilin kalender Hijriah di web, cara paling gampang ya tinggal pasang library atau panggil API pihak ketiga. Dan hampir semua library/API kalender Hijriah yang gampang ditemukan itu defaultnya pakai kriteria Umm al-Qura, kalender resmi Arab Saudi.

Masuk akal kalau itu yang dipakai. Dokumentasinya lengkap, gampang diintegrasikan, gratis. Tapi Umm al-Qura itu dirancang untuk kebutuhan Arab Saudi, bukan hasil rukyah atau sidang isbat Kemenag RI. Makanya bisa beda ±1 hari dari yang diumumkan di Indonesia, persis kejadian yang bikin viral itu.

Jadi kemungkinan besar itu bukan “bug” dalam arti kesalahan kode. Itu bug karena pakai sumber data yang salah untuk konteks Indonesia.

Isi gap-nya

Setelah nyadar itu, saya mikir: kalau developer lain di Indonesia mau bikin aplikasi yang nampilin kalender Hijriah dan pengen datanya sesuai keputusan Kemenag (bukan Saudi), opsinya dikit banget. Kebanyakan harus scraping manual atau maintain tabel sendiri (spoiler: developer =/= ahli astronomi).

Makanya saya bikin mabims.dev: API kalender Hijriah yang sumbernya dari kalender resmi Kemenag RI, pakai kriteria Neo MABIMS untuk fallback di luar cakupan. Gratis, tanpa API key, tinggal panggil endpoint.

Realistisnya… saya nggak tahu bakal banyak yang pakai atau nggak. Tapi minimal ada satu aplikasi yang pasti pakai: kajian.malangmengaji.com, yang saya bangun juga. Kalau nggak ada developer lain yang butuh, ya sudah… API ini akan tetap jalan buat aplikasi saya sendiri.

Tapi kalau kamu develop aplikasi yang butuh kalender Hijriah yang akurat buat Indonesia, silakan pakai. Gratis, open source, dan mudah-mudahan nggak akan pernah perlu dihapus karena ketauan salah tanggal :)

Coba sekarang:

curl "https://api.mabims.dev/api/v1/today"

Dokumentasi lengkap ada di mabims.dev/quickstart.