Quickstart

Base URL:

https://api.mabims.dev/api/v1

Selamat datang di MABIMS API. Di halaman ini Anda akan membuat permintaan pertama dalam waktu kurang dari satu menit: mengambil tanggal Hijriah hari ini, mengonversi tanggal Masehi ke Hijriah, lalu mencobanya langsung dari kode. Tidak perlu API key, tidak perlu registrasi. Cukup panggil endpoint-nya.

Tanggal Hijriah hari ini

Kasus penggunaan yang paling umum: berapa tanggal Hijriah hari ini?

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

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

Contoh kode

Pakai bahasa apa pun yang bisa HTTP request. Tidak perlu library khusus.

const res = await fetch("https://api.mabims.dev/api/v1/today");
const { day, month_name, year } = (await res.json()).output;
console.log(`${day} ${month_name} ${year} H`);
// "14 Rabiul Akhir 1448 H"

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((res) => res.json())
      .then(setDate);
  }, []);

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

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

const hijriDate = ref(null);

onMounted(async () => {
  const res = await fetch("https://api.mabims.dev/api/v1/today?tz=Asia/Jakarta");
  hijriDate.value = await res.json();
});
</script>

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

today secara default menggunakan Asia/Jakarta (UTC+7). Anda bisa override dengan zona IANA atau UTC offset apa pun:

curl "https://api.mabims.dev/api/v1/today?tz=Asia/Kuala_Lumpur"
curl "https://api.mabims.dev/api/v1/today?tz=UTC+8"

Konversi tanggal tertentu

Konversi dua arah. Arah ditentukan lewat param calendar:

curl "https://api.mabims.dev/api/v1/convert?date=2025-01-03&calendar=gregorian"
curl "https://api.mabims.dev/api/v1/convert?date=1446-07-03&calendar=hijri"

{
  "input": { "date": "2025-01-03", "calendar": "gregorian", "tz": null },
  "output": { "date": "1446-07-03", "calendar": "hijri", "day": 3, "month": 7, "month_name": "Rajab", "year": 1446, "weekday": "Jumat" },
  "source": "mabims",
  "warnings": []
}

Pass calendar=gregorian berarti date adalah tanggal Masehi dan responsnya berupa tanggal Hijriah; calendar=hijri berarti sebaliknya.

Apa saja yang tersedia

Dua endpoint di atas baru permukaannya. Tidak hanya konversi tanggal: MABIMS API juga menyediakan konversi massal, kalender bulanan dan tahunan, hari besar Islam, sampai data visibilitas hilal lengkap dengan grafiknya.

Endpoint	Fungsi
`GET /today`	Tanggal Hijri hari ini (timezone-aware)
`GET /convert`	Konversi satu tanggal (Masehi ↔ Hijriah)
`GET /range`	Konversi bulk hingga 45 hari
`GET /month`	Semua hari dalam satu bulan
`GET /year`	Semua hari dalam satu tahun (12 bulan)
`GET /events`	Hari besar Islam (Ramadan, Idul Fitri, Idul Adha, 1 Muharram, Maulid Nabi)
`GET /hilal/info`	Data visibilitas hilal (JSON)
`GET /hilal/viz`	Grafik langit hilal (PNG 720×1280)
`GET /hilal/map`	Peta visibilitas hilal (PNG 720×1280)
`GET /hilal/history`	Riwayat visibilitas hilal per bulan

Referensi API per endpoint

GET /todayTanggal Hijri hari ini (timezone-aware)

GET /convert & /rangeKonversi satu tanggal dan konversi massal

GET /month & /yearSemua hari dalam satu bulan atau satu tahun

GET /eventsHari besar Islam

GET /hilalData visibilitas hilal, grafik langit, peta, dan riwayat

GET /metaCakupan data dan status komputasi

OpenAPI SpecSpesifikasi OpenAPI 3.1 lengkap

Lebih ringan lewat SDK

Mau hasilnya offline tanpa panggil API? Pakai mabims-hijri, package npm dengan data 2023-2026 ter-bundle di dalamnya. Cocok untuk aplikasi yang butuh tanggal Hijriah tanpa jaringan, tanpa khawatir rate limit.

npm install mabims-hijri

Detail lengkapnya: Dokumentasi SDK.

Mau lihat hasilnya tanpa menulis kode? Buka kalender Hijriah MABIMS, kalender sebulan penuh, hari penting Islam, dan data hilal dalam satu halaman.

Selalu periksa `source`

Setiap respons membawa field source:

mabims: dari data publik Kemenag
mabims-computed: dihitung dengan kriteria Neo MABIMS
mabims-retro: di bawah tabel kurasi (butuh retro=true): kriteria Neo MABIMS diproyeksikan ke belakang. Kriteria baru diperkenalkan pada 2022 dan data kurasi baru mulai 2023, jadi tanggal sebelum itu adalah ekstrapolasi murni

Kenapa ini penting? Jika source = mabims, datanya resmi dari Kemenag, bisa dipakai tenang. Data kurasi ini diperbarui setiap tahun, biasanya pertengahan Oktober. Untuk tanggal lebih dari itu, respons disajikan dari mabims-computed, dihitung dengan kriteria Neo MABIMS, akurat tapi bukan pengumuman resmi.

Kalau Anda menyimpan hasil API di cache aplikasi Anda, usahakan refresh cachenya minimal 1x setahun, tepat ketika data mabims diperbarui untuk tahun baru.

`Warnings`

Perlakukan warnings sebagai pemberitahuan kepada pengguna apabila ia mengandung payload (tidak kosong).

Warning	Artinya
Date is outside the curated MABIMS table; computed with the Neo MABIMS criteria (moon altitude >= 3 deg and elongation >= 6.4 deg at local sunset, seen anywhere across the coastal observation sites of Indonesia).	Tanggal di luar tabel, dihitung dengan kriteria Neo MABIMS.
Hijri month {ym} is close to the Neo MABIMS visibility threshold; the officially announced date may shift by one day.	Bulan Hijri berada di batas ambang kriteria visibilitas, tanggal resmi bisa bergeser ±1 hari.
kemenag_override: 1 {bulan} {tahun} H resmi {tanggal} (Sidang Isbat; kalender terbit Kemenag: {tanggal}, delta ±n hari).	Bulan ini dikoreksi lewat Sidang Isbat, tanggal resminya beda dengan kalender terbit. Detail: Sidang Isbat & Koreksi.

Panduan integrasi lengkap

Butuh panduan step-by-step untuk kasus spesifik?

Tampilkan di WebsiteTutorial lengkap: JavaScript, PHP, WordPress, plus cache server & widget kalender bulanan

Integrasikan ke App iOS/AndroidStrategi cache offline-first untuk app native: pola /year + /today, contoh Swift & Kotlin

Akses & Batas Rate

Semua reads bersifat publik

Setiap endpoint di /api/v1/* bersifat publik, tidak perlu API key dan tidak perlu registrasi, untuk memudahkan para developer mengintegrasikannya ke aplikasi / web.

Akses browser vs server

Klien	Perilaku
Server-side (curl, backend, cron)	Selalu diizinkan, CORS tidak berlaku
Browser	Diizinkan dari origin mana pun

Respons dilayani dengan header CORS yang fleksibel, sehingga aplikasi client-side di domain mana pun dapat memanggil API secara langsung.

Batas rate & caching

CDN edge (Bunny CDN): 4 request/detik per IP secara terus-menerus, burst 24. Ini adalah batas rate utama; sebagian besar permintaan tidak pernah mencapai origin.
Origin (FastAPI): 240/menit per IP sebagai cadangan jika CDN dilewati. Endpoint hilal (/hilal/info, /hilal/viz) lebih ketat di origin (60 atau 30/jam) karena komputasi berat, namun respons-nya di-cache publik di CDN (s-maxage=86400) sehingga edges hanya sekali render per hari.
Permintaan yang identik dilayani dari cache CDN dan tidak pernah mencapai origin. Dengan jutaan permintaan/hari, origin hanya melihat sekitar satu permintaan per lokasi edge per sumber daya yang di-cache per hari.
Respons /today membawa TTL yang kedaluwarsa tepat pada tengah malam waktu lokal, sehingga jawaban yang di-cache tidak pernah basi setelah pergantian hari.

Batas lebih tinggi / penggunaan komersial

Membutuhkan rate yang dijamin, SLA, atau ingin mendukung proyek ini? Hubungi halo@pixostudio.id.