Quickstart

Base URL:

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

Welcome to MABIMS API. This page gets your first request done in under a minute: fetch today’s Hijri date, convert a Gregorian date to Hijri, then call it straight from your code. No API key, no registration. Just hit the endpoint.

Today’s Hijri date

The most common use case: what Hijri date is it right now?

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

Code examples

Use any language that can make an HTTP request. No special libraries needed.

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>Loading Hijri date...</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>Loading Hijri date...</div>
</template>

today defaults to Asia/Jakarta (UTC+7). Override with any IANA zone or UTC offset:

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

Convert a specific date

Two directions. The calendar param picks which one:

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

With calendar=gregorian, date is a Gregorian date and the response is its Hijri counterpart; calendar=hijri means the reverse.

What’s available

The two endpoints above are just the surface. It’s not only date conversion: MABIMS API also ships bulk conversion, monthly and yearly calendars, Islamic events, and hilal visibility data with its sky chart.

Endpoint	Function
`GET /today`	Today’s Hijri date (timezone-aware)
`GET /convert`	Single date conversion (Gregorian ↔ Hijri)
`GET /range`	Bulk conversion up to 45 days
`GET /month`	All days in a month
`GET /year`	All days in a year (12 months)
`GET /events`	Islamic events (Ramadan, Eid al-Fitr, Eid al-Adha, 1 Muharram, Maulid Nabi)
`GET /hilal/info`	Hilal visibility data (JSON)
`GET /hilal/viz`	Hilal sky chart (PNG 720×1280)
`GET /hilal/map`	Hilal visibility map (PNG 720×1280)
`GET /hilal/history`	Hilal visibility history per month

API reference per endpoint

GET /todayToday's Hijri date (timezone-aware)

GET /convert & /rangeSingle date conversion and bulk conversion

GET /month & /yearAll days in a month or year

GET /eventsIslamic events

GET /hilalHilal visibility data, sky chart, map, and history

GET /metaData coverage and computation status

OpenAPI SpecFull OpenAPI 3.1 specification

Or go offline with the SDK

Want results without hitting the API? Use mabims-hijri, an npm package with 2023-2026 data bundled inside. Ideal for apps that need Hijri dates without a network call, no rate limits to worry about.

npm install mabims-hijri

Full details: SDK documentation.

Want to see the results without writing code? Open the MABIMS Hijri calendar, a full month view, key Islamic dates, and hilal data on one page.

Always check `source`

Every response carries a source field:

mabims: authoritative, from the curated table (2023-01-23 to 2026-12-31)
mabims-computed: computed with Neo MABIMS criteria (after 2026-12-31, up to 2100)
mabims-retro: below the curated table (requires retro=true): Neo MABIMS criteria projected backwards. The criteria were only introduced in 2022 and curated data starts 2023, so earlier dates are pure extrapolation

Why this matters: when source = mabims, the data is officially from Kemenag, safe to trust. This curated table is refreshed yearly, usually mid-October. Dates beyond it are served from mabims-computed, computed with Neo MABIMS criteria, accurate but not an official announcement.

If you cache API responses in your app, make sure to refresh the cache at least once a year, right when mabims data is updated for the new year.

`Warnings`

Treat warnings as user-facing notices when non-empty.

Warning	Meaning
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).	Outside table, computed with Neo MABIMS criteria.
Hijri month {ym} is close to the Neo MABIMS visibility threshold; the officially announced date may shift by one day.	Month is near the visibility threshold, official date may shift ±1 day.
kemenag_override: 1 {month} {year} H official {date} (Sidang Isbat; published Kemenag calendar: {date}, delta ±n days).	This month was corrected via a Sidang Isbat, the official date differs from the published calendar. See Sidang Isbat Corrections.

Full integration guides

Need a step-by-step walkthrough for a specific use case?

Show on a WebsiteFull tutorial: JavaScript, PHP, WordPress, plus server caching and monthly calendar widgets

Integrate into iOS/Android AppsOffline-first cache strategy for native apps: /year + /today pattern with Swift & Kotlin examples

Access & Rate Limits

Reads are public

Every endpoint under /api/v1/* is public: no keys, no registration. Calendar dates aren’t secrets, and gating them would only push integrators to worse data sources.

Browser vs server access

Client	Behaviour
Server-side (curl, backend, cron)	Always allowed, CORS doesn’t apply
Browser	Allowed from any origin

Responses are served with permissive CORS headers, so client-side apps on any domain can call the API directly.

Rate limits & caching

CDN edge (Bunny CDN): 4 requests/second sustained per IP, burst of 24. This is the primary rate limit; most requests never reach the origin.
Origin (FastAPI): 240/min per IP as a fallback if the CDN is bypassed. Hilal endpoints (/hilal/info, /hilal/viz) are stricter at the origin (60 or 30/hour) due to heavy computation, but their responses are publicly CDN-cached (s-maxage=86400) so edges only render once per day.
Identical requests are served from CDN cache and never reach the origin. At millions of requests/day the origin sees roughly one request per edge location per cached resource per day.
/today responses carry a TTL that expires exactly at local midnight, so cached answers are never stale past date rollover.

Higher limits / commercial use

Need a guaranteed rate, SLA, or want to support the project? Contact halo@pixostudio.id.