GET /convert & /range

GET /convert

Mengubah satu tanggal dari satu kalender ke kalender lain. Arah perubahan ditentukan oleh calendar.

GET/api/v1/convert?date={YYYY-MM-DD}&calendar={gregorian|hijri}&retro={true|false}

Test Request

Parameter

Parameter	Tipe	Wajib	Deskripsi
date	string	ya	Tanggal ISO (YYYY-MM-DD)
calendar	string	tidak (bawaan gregorian)	Kalender tanggal masukan
retro	true / false	tidak (bawaan false)	Mengaktifkan tanggal hasil perhitungan untuk tahun sebelum tabel tersedia, sampai 1 Januari 1945. Data ini diberi tanda mabims-retro. Lihat cakupan data

Contoh

curl

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

JavaScript

const res = await fetch("https://api.mabims.dev/api/v1/convert?date=2025-01-03&calendar=gregorian");
const data = await res.json();
console.log(data.output.date); // "1446-07-03"

PHP

$response = GuzzleHttp\request('GET', 'https://api.mabims.dev/api/v1/convert?date=2025-01-03&calendar=gregorian');
$data = json_decode($response->getBody(), true);
echo $data['output']['date']; // "1446-07-03"

Respons

200 OK

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

400 — format tanggal tidak valid atau kalender tidak dikenal

{
  "error": {
    "code": "invalid_date",
    "message": "'bukan-tanggal' is not a valid ISO date (YYYY-MM-DD)."
  }
}

code	Penyebab
invalid_date	Format tanggal bukan YYYY-MM-DD
invalid_calendar	Parameter calendar bukan gregorian atau hijri
missing_parameter	Query parameter date tidak ada
out_of_coverage	Tanggal di luar cakupan tabel; lihat /meta
invalid_retro	Parameter retro bukan nilai boolean (menerima true/false, 1/0)

Flag boolean menerima true/false (tidak peka huruf besar/kecil) dan 1/0; tanpa param = false.

404 — date_not_found: tidak ada pasangan untuk tanggal tersebut

{
  "error": {
    "code": "date_not_found",
    "message": "No calendar pair exists for 2023-01-01 (gregorian). See /api/v1/meta for coverage."
  }
}

Catatan

/convert tidak bergantung pada zona waktu. Hanya /today yang menerima parameter tz, karena tanggal “hari ini” bergantung pada lokasi Anda.

---

GET /range

Mengubah setiap hari dalam rentang yang diminta.

GET/api/v1/range?start={YYYY-MM-DD}&end={YYYY-MM-DD}&calendar={gregorian|hijri}&retro={true|false}

Test Request

Parameter

Parameter	Tipe	Wajib	Deskripsi
start / end	string	ya	Tanggal ISO; start ≤ end; rentang maks 45 hari
calendar	string	tidak (bawaan gregorian)	Kalender tanggal awal dan akhir
retro	true / false	tidak (bawaan false)	Mengaktifkan tanggal hasil perhitungan untuk tahun sebelum tabel tersedia, sampai 1 Januari 1945. Data ini diberi tanda mabims-retro. Lihat cakupan data

Contoh

curl

curl "https://api.mabims.dev/api/v1/range?start=2025-01-01&end=2025-01-03&calendar=gregorian"

JavaScript

const res = await fetch("https://api.mabims.dev/api/v1/range?start=2025-01-01&end=2025-01-03&calendar=gregorian");
const data = await res.json();
data.items.forEach(i => console.log(i.gregorian, "→", i.hijri));

PHP

$response = GuzzleHttp\request('GET', 'https://api.mabims.dev/api/v1/range?start=2025-01-01&end=2025-01-03&calendar=gregorian');
$data = json_decode($response->getBody(), true);
foreach ($data['items'] as $item) {
    echo $item['gregorian'] . ' → ' . $item['hijri'] . PHP_EOL;
}

{
  "input": { "start": "2025-01-01", "end": "2025-01-03", "calendar": "gregorian" },
  "count": 3,
  "items": [
    { "gregorian": "2025-01-01", "hijri": "1446-07-01", "weekday": "Rabu", "source": "mabims" },
    { "gregorian": "2025-01-02", "hijri": "1446-07-02", "weekday": "Kamis", "source": "mabims" },
    { "gregorian": "2025-01-03", "hijri": "1446-07-03", "weekday": "Jumat", "source": "mabims" }
  ],
  "warnings": []
}

Setiap item memiliki source sendiri. Rentang yang melewati batas data MABIMS dapat berisi gabungan data publik dan hasil perhitungan.

Untuk calendar=hijri, rentang dapat melampaui cakupan tabel publik. Bulan Hijriah di luar tabel dihitung dengan kriteria Neo MABIMS hingga tahun 2100. Batas start/end tetap 45 hari.

Penyimpanan di cache

Hasil untuk setiap masukan tidak berubah dan dikirim dengan Cache-Control: max-age=86400. Hasil ini aman disimpan di cache mana pun selama satu hari penuh.

Setiap respons juga menyertakan ETag. Kirim If-None-Match: <etag> dan server menjawab 304 Not Modified (tanpa body) bila data belum berubah, dengan Cache-Control dan ETag yang sama.

Kesalahan

Semua kesalahan mengembalikan JSON dengan format standar:

{
  "error": {
    "code": "range_too_large",
    "message": "Range is limited to 45 days."
  }
}

code	HTTP	Penyebab
invalid_step	400	Step bukan day
range_too_large	400	Rentang > 45 hari
out_of_coverage	400	Tanggal di luar cakupan tabel
invalid_retro	400	Parameter retro bukan nilai boolean (menerima true/false, 1/0)
rate_limit_exceeded	429	Terlalu banyak permintaan; tunggu sesuai header Retry-After (detik)
not_found	404	Path tidak dikenal (respons error seragam)

Flag boolean menerima true/false (tidak peka huruf besar/kecil) dan 1/0; tanpa param = false.