GET /today

Returns the Hijri date for “now” in the requested timezone. This is the endpoint most consumer apps poll, and it is tuned for it: responses carry dynamic edge-cache TTLs so a CDN serves nearly all traffic.

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

Test Request

Parameters

Parameter	Type	Required	Description
tz	string	no (default Asia/Jakarta, UTC+7)	IANA zone name (Asia/Kuala_Lumpur) or UTC offset (UTC+7, +08:00)
next	boolean	no (default false)	Set true to also return the Hijri date that becomes current after this evening’s maghrib (the next civil day’s mapping)

Example

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"

Response

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

The input.tz field echoes the resolved timezone so clients can confirm what was used.

The date after maghrib (next)

The Hijri day begins at maghrib, so the date rolls over before midnight. With next=true the response also carries a next object: the Hijri date that becomes current after this evening’s maghrib.

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

Switch your display to next once your local maghrib has passed. The API does not compute sunset, so gate the flip on your own prayer-time clock. Without next=true the field is absent and the response is unchanged.

next.source is reported separately because it may differ from the top-level source when the rollover crosses the curated-table edge.

Errors

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

code	HTTP	Cause
invalid_timezone	400	Unrecognized timezone
invalid_next	400	next param is not a boolean value (accepts true/false, 1/0)

Boolean flags accept true/false (case-insensitive) and 1/0; absent = false.

Immutable variant

GET/api/v1/today/{target_date}

Test Request

Same conversion for any given Gregorian date, useful as a stable, cache-forever resource and for replaying historical days:

Caching behaviour

• Cache-Control: public, max-age=60, s-maxage=<seconds until local midnight>
• A cache miss at 06:00 is cached at the edge for ~18 hours; a miss at 23:59 expires right after midnight so the date rolls over immediately.
• At millions of requests/day the origin sees roughly one request per edge location per day.
• Every response also carries an ETag. Send If-None-Match: <etag> and the server answers 304 Not Modified (empty body) when the data has not changed, with the same Cache-Control and ETag headers.