API Kalender MABIMS | Blog

Why Search for Hilal in Sabang?

Sat, 29 Aug 2026 00:00:00 GMT

One of my favorite endpoints on mabims.dev isn’t /today or /convert, but /hilal/viz. This endpoint generates a 720×1280 PNG showing a complete evening sky visualization with moon position, MABIMS criteria pass/fail status, and a sky chart with stars.

No other Hijri calendar API (at least that I’ve found) has this feature. So this post discusses how it works, from astronomy to pixel rendering.

Why Sabang?

This is the question I get most often. The answer is simple: Sabang is Indonesia’s westernmost point.

For moon sighting (rukyah), geographic position matters — the further west, the later sunset occurs. This means if the hilal doesn’t meet criteria elsewhere, its last chance will be in Sabang.

This isn’t an official MABIMS rule about “must use Sabang,” but it’s a practical reference point that makes sense for representing Indonesia-wide hilal visibility in a single coordinate.

How It Works

A simplified version of the actual implementation:

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 the sighting evening

If you request visibility for Ramadan, this endpoint doesn’t calculate the 1st of Ramadan itself — it goes back to the 29th evening of Sya’ban, because that’s the actual evening observed to determine whether tomorrow marks the start of Ramadan. This is the fundamental logic of rukyah: you observe the hilal at the end of the current month, not at the start of the target month.

2. Calculate that evening’s astronomy, from Sabang

Two categories of data are computed:

Geocentric criteria — moon_alt (altitude), moon_az (azimuth), sun_alt, and elongation (angular distance between moon and sun). These are the numbers directly compared against MABIMS thresholds.
Observer-clock times — illumination, local sunset time, and moonset time. This is what’s displayed as additional info on the bottom card.

3. Check Neo MABIMS thresholds

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

Both conditions must be met simultaneously. If either fails, the hilal is considered not to meet visibility criteria, even if the moon is above the horizon.

Example Result

The screenshot above shows visibility for 1 Muharram 1448 H (evaluating the evening of 29 Dzulhijjah 1447 H, June 15 2026, from Sabang):

Moon altitude +5.0° (passes, threshold ≥3.0°)
Elongation 7.0° (passes, threshold ≥6.4°)
Illumination 0.2% — very thin, the hilal is extremely young
Sunset 18:53, moonset 19:11, only 18 minutes apart

Status: VISIBLE, though with not much margin.

Why Bother Building This?

Because raw numbers (moon_alt: 5.2, elongation: 8.7) aren’t intuitive for most people, including myself. But once visualized — see the moon’s position relative to the horizon, see the green/red pill, see the criteria table — it becomes much easier to digest. This endpoint isn’t just for developers who need JSON, but for anyone curious about “how can the hilal be declared visible/not visible” without needing to understand astronomy.

Try it yourself on the playground:

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

Change month and year to the Hijri month you want to check. Full parameter documentation at mabims.dev/en/endpoints/hilal.

Integration Tutorial

Fri, 28 Aug 2026 00:00:00 GMT

I built this API for developers, and I don’t want integration to stop at documentation with just GET /today and that’s it. So in this post I’ll show examples from the simplest to more proper setups: plain JavaScript, Vue, React, and mobile apps.

Simplest: JavaScript

If your website only needs to display today’s Hijri date, it’s actually this simple:

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

console.log(data);

The response looks like this:

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

Just grab the output field to display. It’s already complete, no parsing needed:

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

So if your website header has:

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

Just call the function above and the Hijri date will appear.

No library installation. No API key. No need to build your own server just to fetch a Hijri date.

Using timezones

This is a part I think is important.

A Hijri date isn’t just about converting Gregorian → Hijri. Timezones also determine what “today” means.

For example, your server is in the US, but most of your users are in Indonesia. You don’t want 00:30 WIB to be treated as the previous day because your server is still on the day before.

mabims.dev provides a timezone override so you can specify which timezone to use. Use the tz parameter:

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

const data = await response.json();

For apps targeting Indonesia, I usually explicitly use Asia/Jakarta, Asia/Makassar, or Asia/Jayapura as needed.

In Vue

If you use Vue, the concept is the same. The difference is we store the API result in state.

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

Done.

I actually recommend this approach over including a Hijri calendar library that’s much larger, if your app’s need is just displaying the Hijri date.

In React

React is more or less the same:

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>Loading Hijri date...</span>;
  }

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

No additional dependencies.

React just fetches the API → stores the result → renders.

If you need a specific date

/today works when all you need is today’s Hijri date.

But what if the user picks a date from a date picker?

Say the user picks:

August 17, 2026

You can use the conversion endpoint:

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

const data = await response.json();

This is useful for calendars, forms, articles with publication dates, or date search features.

For example, the user picks August 17, 2026 and you want to display the Hijri version. Just send that Gregorian date to the API.

Don’t forget to check `source`

There’s one thing I think is quite important when consuming this API.

The mabims.dev response includes a source field.

Simply put, there are two possibilities:

mabims — the date comes from Kemenag’s official table.
mabims-computed — the date was calculated using Neo MABIMS criteria as a fallback when the date is outside the table’s coverage.

Why do I expose this?

Because I don’t want the API to silently return computed results while developers assume it’s the official date from Kemenag.

If your app is serious about the calendar, you can store or display this information.

if (data.source === "mabims-computed") {
  console.log("Date uses Neo MABIMS computed result");
}

And if the API returns warnings, don’t just throw them away.

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

For mobile apps

If you’re building an Android/iOS app, the principle is actually the same.

Whether it’s Flutter, React Native, Kotlin, Swift, or any other framework — as long as your app can make HTTP requests, you can call this API.

Pseudocode:

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

The API doesn’t care whether the request comes from a browser, server, or mobile app.

But should every page make its own API request?

Now we’re getting into architecture.

If your website has 100 components that all need the Hijri date, don’t have every component call fetch("/today") independently.

Fetch once, then share the result.

On the frontend, you can create your own composable/hook/service.

For example in 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("Failed to fetch Hijri date");
  }

  return response.json();
}

Then other components just use that function.

For larger apps, you can even cache the result since the Hijri date doesn’t change every few seconds.

What about SSR or backend?

This is even more interesting.

If you’re using Next.js, Nuxt, Laravel, Rails, Django, or any other backend, you can also call mabims.dev from your server.

Simple example:

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

const hijriDate = await response.json();

Then your server sends that date to the browser.

The advantage is the Hijri date can already be available when the page first renders.

But if you do this, still think about caching. There’s no point in your server requesting the same date multiple times a day.

So when should you use this API?

In my opinion, if your need is just:

“I want to display the Hijri date on my website.”

Don’t build your own calendar system.

Don’t maintain your own table.

Don’t copy-paste dates from a PDF calendar into a database.

And don’t expect a calendar library that defaults to Umm al-Qura to automatically match Indonesia’s needs.

Just:

Website / App
      ↓
mabims.dev
      ↓
MABIMS-based Hijri date

If you need today’s date, use /today.

If you need to convert a specific date, use /convert.

If your app needs a specific timezone, specify it explicitly.

And if your app is administratively or religiously significant, always treat the API as a technical data source, not a replacement for official Kemenag decisions.

That’s it. Hope it helps!

The Story Behind MABIMS API

Thu, 27 Aug 2026 00:00:00 GMT

There’s a funny (and slightly sad) story behind mabims.dev.

Kemenag’s website used to display Hijri dates on its homepage. Many people, including myself, relied on it. Just open the website, check the top corner, and you’d know today’s Hijri date.

Until one day, a viral post appeared. The Kemenag calendar said the 30th, but the Kemenag website said the 1st of the next month had already started. Off by one day.

The post spread everywhere. People questioned why an official site could differ from the calendar it itself issued.

The solution? Just delete it

At the time I didn’t know the details behind it — whether it was a bug, a miscalculation, or what. What I knew was that the ending was remarkably elegant: the Hijri date on the website was deleted. Not fixed, deleted. Problem solved, I guess… but it felt kind of off.

A few years later, I became a junior dev

When I started working as a developer, I finally understood what probably happened. If you want to display a Hijri calendar on a website, the easiest way is to use a library or call a third-party API. And almost every Hijri calendar library/API you can easily find defaults to Umm al-Qura — Saudi Arabia’s official calendar.

It makes sense that this is what’s used. The documentation is thorough, easy to integrate, free. But Umm al-Qura is designed for Saudi Arabia’s needs, not for Kemenag RI’s moon sighting or isbat session results. That’s why it can differ by ±1 day from what’s announced in Indonesia — exactly the incident that went viral.

So it was likely not a “bug” in the sense of a code error. It was a bug caused by using the wrong data source for the Indonesian context.

Filling the gap

After realizing this, I thought: if other developers in Indonesia want to build an app that displays the Hijri calendar and want it to match Kemenag’s decision (not Saudi’s), the options are very limited. Most have to scrape manually or maintain their own table (spoiler: developer ≠ astronomer).

That’s why I built mabims.dev: a Hijri calendar API sourced from Kemenag RI’s official calendar, using Neo MABIMS criteria for fallback beyond table coverage. Free, no API key, just call the endpoint.

Realistically… I don’t know if many people will use it. But at least one app will definitely use it: kajian.malangmengaji.com, which I also built. If no other developers need it, fine — this API will keep running for my own app.

But if you’re developing an app that needs an accurate Hijri calendar for Indonesia, feel free to use it. Free, open source, and hopefully it will never need to be taken down because it was caught showing the wrong date :)

Try it now:

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

Full documentation at mabims.dev/quickstart.