> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bilauitmcuti.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Malaysia Public Holidays

> Fetch Malaysia public holidays by year, nationwide coverage or any of 16 states and territories with the free Bila UiTM Cuti API.

Holiday filter options (meta) and Malaysia public holiday rows with optional coverage and state filters.

### Public Holiday Options (Meta)

`GET` `/api/v1/public-holiday/meta`

Returns public holiday option metadata for building filters and navigation: available years, coverage modes (`all` vs `nationwide`), and the full states/territories list. In holiday rows, nationwide means `states` lists all 16 territory slugs. Use `GET /api/v1/public-holiday` for rows and aggregates (including date range in `meta`).

#### Response Fields

| Field | Type | Description | Example |
| - | - | - | - |
| `apiVersion` | string | API version included in the response payload. | 1 |
| `baseUrl` | string | Public base URL for this API. | [https://api.bilauitmcuti.com](https://api.bilauitmcuti.com) |
| `defaultYear` | integer | Default holiday year for this dataset. | 2026 |
| `yearOptions` | object\[] | Available year options in dataset. | `[{ "value": 2026, "label": "2026" }]` |
| `coverageOptions` | object\[] | Coverage filter labels for `GET /api/v1/public-holiday?coverage=…` (`all` = full dataset, `nationwide` = nationwide rows only). | `[{ "value": "all", "label": "All States" }, { "value": "nationwide", "label": "Nationwide only" }]` |
| `stateOptions` | object\[] | Complete states and territories list in slug format. | `[{ "value": "selangor", "label": "Selangor" }]` |

### Malaysia Public Holidays

`GET` `/api/v1/public-holiday`

Returns Malaysia public holiday rows from `public-holiday.json`. Optional `year` scopes rows to a calendar year (defaults to `defaultYear` from the dataset, currently 2026 while that year is published). Optional `coverage` selects the full dataset for that year, nationwide-only rows, or (by default) you can filter with `state` for one of 16 states/territories. This endpoint focuses on holiday results and aggregates (including `meta.dateRange`); use `/api/v1/public-holiday/meta` for option lists only.

#### Query Parameters

| Name | Type | Description | Example |
| - | - | - | - |
| `year` | integer | Calendar year to return (must appear in `yearOptions` from `/api/v1/public-holiday/meta`). Omit to use `defaultYear` (the recommended active year for the product). | 2026 |
| `coverage` | string | Geographic coverage preset. `all` returns every row (ignores `state`). `nationwide` returns only rows where `states` lists all 16 territories (nationwide holidays). Omit to use optional `state` filtering: with `state`, returns nationwide rows plus rows that include that territory. | nationwide |
| `state` | string | State/territory filter (slug format). Ignored when `coverage=all`. Accepted values: johor, kedah, kelantan, melaka, negeri-sembilan, pahang, perak, perlis, pulau-pinang, sabah, sarawak, selangor, terengganu, kuala-lumpur, labuan, putrajaya. | selangor |

#### Response Fields

| Field | Type | Description | Example |
| - | - | - | - |
| `apiVersion` | string | API version included in the response payload. | 1 |
| `baseUrl` | string | Public base URL for this API. | [https://api.bilauitmcuti.com](https://api.bilauitmcuti.com) |
| `defaultYear` | integer | Default holiday year for this dataset. | 2026 |
| `yearOptions` | object\[] | Available year options in dataset. | `[{ "value": 2026, "label": "2026" }]` |
| `query` | object | Applied filters returned for traceability. | `{ "year": 2026, "state": "selangor", "coverage": null }` |
| `total` | integer | Number of holiday rows returned after filtering. | 8 |
| `meta` | object | Summary data for returned rows: nationwide row count (rows where `states` contains all 16 territories), filtered date range, and per-state totals (nationwide rows are included for every state). | `{ "nationwideTotal": 4, "dateRange": { "startDate": "2026-01-01", "endDate": "2026-12-25" }, "stateTotals": [{ "state": "selangor", "label": "Selangor", "total": 5 }] }` |
| `holidays` | object\[] | Holiday rows: nationwide holidays list all 16 territory slugs; others list only the slugs where the holiday applies. | `[{ "id": "birthday-of-sultan-of-selangor-2026-12-11-st-selangor", "name": "Birthday of Sultan of Selangor", "date": "2026-12-11", "day": "Friday", "states": ["selangor"], "isSubjectToChange": false }]` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.