GET /month, /months & /year

GET /month

Convenience wrapper that resolves a whole month grid.

GET/api/v1/month?year={Y}&month={M}&calendar={hijri|gregorian}&retro={true|false}

Test Request

Parameters

Parameter	Type	Required	Description
year	int	yes	Hijri or Gregorian year
month	int	yes	Month 1–12
calendar	string	no (default hijri)	Calendar of the year input
retro	true / false	no (default false)	Unlocks computed retro dates below the curated table (down to 1945-01-01), tagged mabims-retro. See data coverage for the reason why

Example

curl

curl "https://api.mabims.dev/api/v1/month?year=1447&month=1&calendar=hijri"

JavaScript

const res = await fetch("https://api.mabims.dev/api/v1/month?year=1447&month=1&calendar=hijri");
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/month?year=1447&month=1&calendar=hijri');
$data = json_decode($response->getBody(), true);
foreach ($data['items'] as $item) {
    echo $item['gregorian'] . ' → ' . $item['hijri'] . PHP_EOL;
}

For calendar=hijri the response contains every Gregorian date onto which that Hijri month maps — exactly what a Hijri month-view needs (29–30 items). Hijri months beyond the public table (e.g. next year) are still resolved from the Neo MABIMS computed tier while within the supported range. Same item shape as /range.

GET /months

Returns the 12 Hijri month names with their numbers. Static, no parameters, cacheable — use this to populate dropdowns or labels in your UI.

GET/api/v1/months

Test Request

Example

curl

curl "https://api.mabims.dev/api/v1/months"

JavaScript

const res = await fetch("https://api.mabims.dev/api/v1/months");
const data = await res.json();
data.months.forEach(m => console.log(m.number, m.name));

PHP

$response = GuzzleHttp\request('GET', 'https://api.mabims.dev/api/v1/months');
$data = json_decode($response->getBody(), true);
foreach ($data['months'] as $month) {
    echo $month['number'] . ' ' . $month['name'] . PHP_EOL;
}

Response

{
  "calendar": "hijri",
  "months": [
    { "number": 1, "name": "Muharram" },
    { "number": 2, "name": "Safar" },
    { "number": 3, "name": "Rabiul Awal" },
    { "number": 4, "name": "Rabiul Akhir" },
    { "number": 5, "name": "Jumadil Awal" },
    { "number": 6, "name": "Jumadil Akhir" },
    { "number": 7, "name": "Rajab" },
    { "number": 8, "name": "Sya'ban" },
    { "number": 9, "name": "Ramadhan" },
    { "number": 10, "name": "Syawal" },
    { "number": 11, "name": "Dzulqa'dah" },
    { "number": 12, "name": "Dzulhijjah" }
  ]
}

GET /year

Returns every day across all 12 months of a year. Much simpler than calling /month 12 times.

GET/api/v1/year?year={Y}&calendar={hijri|gregorian}&retro={true|false}

Test Request

Parameters

Parameter	Type	Required	Description
year	int	yes	Hijri or Gregorian year
calendar	string	no (default hijri)	Calendar of the year input
retro	true / false	no (default false)	Unlocks computed retro dates below the curated table (down to 1945-01-01), tagged mabims-retro. See data coverage for the reason why

Example

curl

curl "https://api.mabims.dev/api/v1/year?year=1447&calendar=hijri"

JavaScript

const res = await fetch("https://api.mabims.dev/api/v1/year?year=1447&calendar=hijri");
const data = await res.json();
console.log(data.count, "days in year", data.input.year);

PHP

$response = GuzzleHttp\request('GET', 'https://api.mabims.dev/api/v1/year?year=1447&calendar=hijri');
$data = json_decode($response->getBody(), true);
echo $data['count'] . ' days in year ' . $data['input']['year'] . PHP_EOL;

{
  "input": { "year": 1447, "calendar": "hijri" },
  "count": 354,
  "months": {
    "1": [
      { "gregorian": "2025-06-27", "hijri": "1447-01-01", "weekday": "Jumat", "source": "mabims" },
      { "gregorian": "2025-06-28", "hijri": "1447-01-02", "weekday": "Sabtu", "source": "mabims" }
    ],
    "2": [ "..." ],
    "3": [ "..." ],
    "4": [ "..." ],
    "5": [ "..." ],
    "6": [ "..." ],
    "7": [ "..." ],
    "8": [ "..." ],
    "9": [ "..." ],
    "10": [ "..." ],
    "11": [ "..." ],
    "12": [ "..." ]
  },
  "warnings": []
}

Each month key contains an array of items with the same shape as /range. The total count is the number of days across the entire year.

For calendar=hijri, months beyond the public table are still served from the Neo MABIMS computed tier while within the supported range.

Errors

code	HTTP	Cause
invalid_month	400	Month is not 1–12
invalid_year	400	Year out of supported bounds
invalid_calendar	400	calendar param is not hijri or gregorian
out_of_coverage	400	Month outside table coverage
date_out_of_supported_range	400	Date exceeds supported range
invalid_retro	400	retro param is not a boolean value (accepts true/false, 1/0)

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