GET /today

Mengembalikan tanggal Hijriah saat ini berdasarkan zona waktu yang diminta. Hasilnya disimpan di cache sampai tengah malam, lalu diperbarui saat hari berganti.

GET/api/v1/today?tz={timezone}&next={true|false}

Test Request

Parameter

Parameter	Tipe	Wajib	Deskripsi
tz	string	tidak (bawaan Asia/Jakarta, UTC+7)	Nama zona IANA (Asia/Kuala_Lumpur) atau selisih waktu UTC (UTC+7, +08:00)
next	boolean	tidak (bawaan false)	Isi true untuk mengembalikan tanggal Hijriah yang mulai berlaku setelah magrib malam ini

Contoh

curl

curl "https://api.mabims.dev/api/v1/today?tz=Asia/Jakarta"

JavaScript

const res = await fetch("https://api.mabims.dev/api/v1/today?tz=Asia/Jakarta");
const data = await res.json();
console.log(data.output.date); // "1448-03-11"

PHP

$response = GuzzleHttp\request('GET', 'https://api.mabims.dev/api/v1/today?tz=Asia/Jakarta');
$data = json_decode($response->getBody(), true);
echo $data['output']['date']; // "1448-03-11"

Respons

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

Kolom input.tz menampilkan zona waktu yang digunakan, sehingga klien dapat memastikannya.

Tanggal setelah magrib (next)

Hari Hijriah dimulai saat magrib, jadi tanggal berganti sebelum tengah malam. Dengan next=true, respons juga menyertakan objek next: tanggal Hijriah yang berlaku setelah magrib malam ini.

curl "https://api.mabims.dev/api/v1/today?tz=Asia/Jakarta&next=true"

{
  "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" },
  "next": { "date": "1448-03-12", "calendar": "hijri", "day": 12, "month": 3, "month_name": "Rabiul Akhir", "year": 1448, "weekday": "Selasa", "source": "mabims" },
  "source": "mabims",
  "warnings": []
}

Ganti tampilan ke next setelah waktu magrib terlewati. API tidak menghitung waktu matahari terbenam, jadi tentukan waktu magrib di sisi klien. Tanpa next=true, field ini tidak ada dan respons tidak berubah.

next.source dilaporkan terpisah karena bisa berbeda dari source utama jika tanggal berikutnya berada di luar tabel.

Kesalahan

{
  "error": {
    "code": "invalid_timezone",
    "message": "..."
  }
}

code	HTTP	Penyebab
invalid_timezone	400	Zona waktu tidak dikenal
invalid_next	400	Parameter next bukan nilai boolean (menerima true/false, 1/0)

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

Versi tetap

GET/api/v1/today/{target_date}

Test Request

Mengembalikan hasil yang sama untuk tanggal Masehi tertentu. Versi ini cocok untuk data yang stabil, dapat disimpan di cache selamanya, dan dapat digunakan untuk melihat tanggal historis:

Penyimpanan di cache

• Cache-Control: public, max-age=60, s-maxage=<detik hingga tengah malam lokal>
• Jika cache kosong pada pukul 06:00, hasilnya disimpan di edge selama sekitar 18 jam. Jika cache kosong pada pukul 23:59, hasilnya kedaluwarsa tepat setelah tengah malam agar tanggal segera berganti.
• Dengan jutaan permintaan per hari, server utama hanya menerima sekitar satu permintaan per lokasi edge setiap hari.
• 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.