Tutorial Embed Kalender Hijriah ke Website dan Aplikasi (Widget + API)

Menampilkan tanggal Hijriah di aplikasi Islami itu terdengar sederhana, sampai Anda coba implementasikan sendiri. Rumus konversi umum (tabular calendar) sering meleset satu atau dua hari dari Kalender Hijriah Indonesia yang dipakai resmi di tanah air, dan perbedaan satu hari itu sangat terasa saat menentukan awal Ramadan atau tanggal peringatan hari besar.

Tutorial ini menunjukkan cara embed kalender Hijriah ke website atau aplikasi Anda menggunakan API Hijriah dari API Indonesia, yang berbasis Kalender Hijriah Indonesia dengan hisab MABIMS. Ada dua pendekatan: konversi on-demand per tanggal, atau fetch kalender satu tahun sekaligus lalu cache di sisi Anda.

Endpoint yang Dipakai

Base URL: https://use.apiindonesia.id/api/v1/hijriah

Method	Endpoint	Parameter	Keterangan
GET	/konversi	tanggal (YYYY-MM-DD)	Konversi satu tanggal Masehi ke Hijriah
GET	/kalender	tahun (Masehi)	Seluruh mapping tanggal untuk satu tahun (saat ini 2026)

1. Konversi Satu Tanggal

Cara paling cepat untuk memulai. Cocok untuk badge tanggal di header aplikasi atau posting blog Islami:

curl "https://use.apiindonesia.id/api/v1/hijriah/konversi?tanggal=2026-08-29" \
  -H "x-api-key: aip_li...x"

Response:

{
  "data": { "gregorian_date": "2026-08-29", "hijri_formatted": "16 Rabiul Awal 1448 H" },
  "meta": { "disclaimer": "Berdasarkan Kalender Hijriah Indonesia (hisab MABIMS)..." }
}

2. Kalender Setahun Sekaligus

Kalau aplikasi Anda menampilkan kalender penuh (seperti widget kalender tahunan), lebih efisien fetch satu tahun lalu simpan di cache lokal. Respons /kalender?tahun=2026 berisi 365 entri, masing-masing dengan gregorian_date, hijri_day, hijri_month_name, dan hijri_year.

import requests
from datetime import date, timedelta

def build_hijri_calendar(api_key: str, year: int = 2026):
    r = requests.get(
        "https://use.apiindonesia.id/api/v1/hijriah/kalender",
        params={"tahun": year},
        headers={"x-api-key": api_key},
    )
    r.raise_for_status()
    mapping = {}
    for row in r.json()["data"]:
        mapping[row["gregorian_date"]] = f'{row["hijri_day"]} {row["hijri_month_name"]} {row["hijri_year"]} H'
    return mapping

def hijri_today(api_key: str):
    return build_hijri_calendar(api_key).get(date.today().isoformat(), "di luar tahun yang di-cache")

print(hijri_today("aip_live_xxx"))

3. Widget Sederhana untuk Website

Kalau Anda tidak mau menulis logika fetch sendiri, potongan React ini cukup untuk menampilkan tanggal Hijriah di navbar:

import { useEffect, useState } from "react";

function HijriBadge() {
  const [label, setLabel] = useState("...");

  useEffect(() => {
    const today = new Date().toISOString().slice(0, 10);
    fetch(`https://use.apiindonesia.id/api/v1/hijriah/konversi?tanggal=${today}`, {
      headers: { "x-api-key": process.env.REACT_APP_API_INDONESIA_KEY },
    })
      .then((r) => r.json())
      .then(({ data }) => setLabel(data.hijri_formatted))
      .catch(() => setLabel("Gagal memuat tanggal"));
  }, []);

  return <span className="hijri-badge">{label}</span>;
}

export default HijriBadge;

Tips caching: hasil konversi untuk tanggal lampau tidak akan berubah, jadi simpan di localStorage atau cache server dan hanya panggil API untuk tanggal hari ini dan ke depan.

Praktik Terbaik

• Cache respons. Kalender tahunan berukuran relatif kecil dan stabil, simpan di memori atau CDN.
• Tampilkan disclaimer. Respons menyertakan meta.disclaimer, sebaiknya ikutkan saat menampilkan tanggal untuk keperluan ibadah.
• Jangan bundling rumus sendiri. Perbedaan metode hisab adalah sumber bug klasik; delegasikan ke API yang mengikuti standar MABIMS.
• Kombinasikan dengan jadwal sholat. Untuk aplikasi Islami lengkap, gabungkan dengan API Jadwal Sholat untuk 514 kabupaten/kota.

FAQ

Akurat nggak dibanding kalender cetak? API ini mengikuti Kalender Hijriah Indonesia berbasis hisab MABIMS, standar yang sama dengan kalender resmi. Tetap ada disclaimer di meta respons.

Tahun apa saja yang didukung endpoint kalender? Saat ini tahun 2026. Untuk tanggal di tahun lain gunakan endpoint /konversi per tanggal.

Berapa biayanya? Tier Free 1.000 hits/bulan, cukup untuk widget dengan caching.

Mulai Sekarang

Pelajari detail parameter di halaman produk API Hijriah, dapatkan API key gratis di dashboard.apiindonesia.id/register, dan baca referensi endpoint di docs.apiindonesia.id.