FAQ

General

What is MABIMS?

MABIMS is the rukyah criterion (Ministers of Religious Affairs of Brunei, Indonesia, Malaysia, Singapore) used by Indonesia’s Ministry of Religious Affairs (Kemenag RI) to determine the start of the Hijriah month, specifically the beginning of Ramadan, Shawwal, and Dhul Hijjah. The Neo MABIMS criterion requires the hilal to be visible at least 3° with an elongation of at least 6.4° at sunset. (See the official explainer from MUI.)

Why is the Hijriah date in my app different from the Indonesian government announcement?

Most Hijriah calendar APIs and apps use the Umm al-Qura (Saudi Arabia) criterion as the default. Because the rukyah method and observation location differ, the result can be ±1 day off from Kemenag’s official decision, especially for the start of fasting, Eid al-Fitr, and Eid al-Adha.

MABIMS vs Umm al-Qura: which is more accurate for Indonesia?

For use in Indonesia, MABIMS is more accurate because it follows Kemenag RI’s official decision through the isbat session, not Saudi authority. Umm al-Qura is designed for Saudi Arabia’s needs and does not represent Indonesia’s rukyah/hisab results.

Is this API an official product of Kemenag or MABIMS?

No. This API is independent, built by PIXO Studio using publicly available Kemenag RI table data as its source. For legal certainty in Islamic law, always refer to official Kemenag announcements.

What if a Sidang Isbat decision differs from the published Kemenag calendar?

The API follows the official Sidang Isbat decision. Any response touching the corrected month (and the month before it) carries a warning prefixed kemenag_override:, and /meta exposes the history in divergences[] plus a table_version that changes with every correction, compare it with your stored value to know when to re-fetch. As long as no correction has ever been applied, these fields are empty and nothing about the API’s behaviour changes. Details: Sidang Isbat Corrections.

Access & Authentication

What is mabims.dev?

mabims.dev is a free open-source API for the Indonesian Hijri calendar. It provides today’s Hijri date, date conversion, monthly and yearly calendars, hilal visibility data, and Islamic event dates, all based on official MABIMS data from Indonesia’s Ministry of Religious Affairs (Kemenag RI). See the About page for details, or browse the MABIMS Hijri calendar directly.

Is this API free and does it require an API key?

Yes, it’s free and requires no authentication. Just call the endpoint directly, with no registration or API key needed.

Can it be used directly from the frontend (client-side)?

Yes. CORS is open, so it can be called directly from the browser on any domain. For rate limit details and fair use policy, see the Access & Rate Limits section in Quickstart.

Technical

What's the difference between source: "mabims" and source: "mabims-computed"?

• `mabims: date taken directly from Kemenag’s publicly available table.
• `mabims-computed: automatically calculated using Neo MABIMS criteria because the date falls outside the table’s coverage (before 2023 or after 2026).

How far ahead does the data go?

Official table data is available for 2023–2026. Outside that range, the API calculates automatically (fallback) using Neo MABIMS criteria up to 2100, the response will tag source: "mabims-computed" instead of "mabims". Dates below the table additionally require retro=true and are tagged mabims-retro.

What timezone is used by default?

Asia/Jakarta (UTC+7) by default, specifically for the /today endpoint. You can override it with the tz parameter using an IANA zone (e.g. Asia/Kuala_Lumpur) or a UTC offset (e.g. UTC+8). The /convert endpoint is timezone-independent since it’s a date conversion, not “what day is it”.

How do I convert between Gregorian and Hijri dates?

Use GET /convert?date=YYYY-MM-DD&calendar=gregorian or calendar=hijri depending on the conversion direction. Full documentation: API Reference /convert & /range.

How do I check hilal visibility for a given month?

Use the /hilal/info endpoint for criterion data, or /hilal/viz for a hilal visibility chart (720×1280 PNG) showing moon position, crescent direction, the VISIBLE/NOT VISIBLE verdict, and the deciding observation point; the criteria are evaluated at coastal sites across Indonesia, and the response reports deciding_site when they are met.

Other

How do I display a Hijri date on a website?

Call the GET /today endpoint for today’s date, then use the day, month_name, and year fields from the JSON response. Quick example:

const res = await fetch("https://api.mabims.dev/api/v1/today");
const data = await res.json();
const { day, month_name, year } = data.output;
document.getElementById("hijri").textContent = `${day} ${month_name} ${year} H`;

For converting a specific date, use GET /convert?date=YYYY-MM-DD&calendar=gregorian. See the Quickstart for a full guide.

What programming languages are supported?

Since MABIMS.dev is a standard REST API, it works with any programming language: JavaScript, PHP, Python, Dart, Swift, Kotlin, or even cURL directly from the terminal. No special libraries needed, just call the endpoint.

Does the data match official Kemenag announcements?

Data tagged source: "mabims" comes directly from Kemenag RI’s public tables, so it matches official announcements. For dates beyond table coverage, source: "mabims-computed" uses Neo MABIMS criteria which may differ from isbat session decisions since it’s an astronomical estimate.

When is the start of Ramadan?

Use the GET /events?year=2026&calendar=gregorian endpoint to get the Ramadan start date. Data comes from Kemenag’s official tables for available years, or is calculated using Neo MABIMS criteria for years beyond table coverage.

Why are Hijri dates different on Google?

Google and most calendar apps use Umm al-Qura (Saudi Arabia’s standard), not MABIMS (Indonesia’s standard). Because the observation location and rukyah method differ, results can be ±1 day off from Kemenag’s official decisions.

What's the difference between hisab and rukyah?

Hisab is the astronomical calculation to determine the moon’s position. Rukyah is the direct visual observation of the hilal (crescent moon). Neo MABIMS criteria combine both: using hisab calculations (moon altitude ≥ 3°, elongation ≥ 6.4°) that represent whether the hilal can be visually observed somewhere in Indonesia. (See also ANTARA English and academic research on these criteria.)

Is this API open source?

Yes, the source code is open on GitHub: PijarAdiluhung/mabims-api. Contributions and issue reports are always welcome.