REST API v1

API Documentation (v1)

Public Malaysia holiday data by year, state, and date. All endpoints return JSON and only expose published holiday records.

Base URL

https://www.malaysia-holiday.dydxsoft.my/api/v1

Auth

None

Format

JSON

No API key

Public consumers do not need an account, bearer token, or request header.

Published data only

Draft and rejected records are excluded from every API response.

Malaysia coverage

Supports all 13 states and 3 federal territories.

Endpoints

Reference

GET

/api/v1/states

Returns every supported Malaysia state and federal territory code.

Request

curl "https://www.malaysia-holiday.dydxsoft.my/api/v1/states"

Response 200

{
  "data": [
    { "code": "JHR", "name": "Johor" },
    { "code": "SBH", "name": "Sabah" },
    { "code": "KUL", "name": "Wilayah Persekutuan Kuala Lumpur" }
  ]
}

Try in Playground

GET

/api/v1/holidays

Returns published holidays for a required year, with optional state and source filters.

Parameter	Required	Allowed values	Description
year	Yes	2000..2100	Holiday year.
state	No	State code or FED	Filters records to one state or territory.
include_source	No	true, false, 1, 0	Includes source metadata when truthy.

Request

curl "https://www.malaysia-holiday.dydxsoft.my/api/v1/holidays?year=2026&state=SBH&include_source=1"

Response 200 (with state filter)

{
  "data": [
    {
      "name": "Pesta Kaamatan",
      "date": "2026-05-30",
      "day_name": "Saturday",
      "is_subject_to_change": false,
      "source": {
        "source_name": "JPM HKA 2026",
        "source_type": "federal_pdf",
        "source_url": "https://example.gov.my/hka2026.pdf",
        "year": 2026,
        "uploaded_at": "2026-05-19T08:00:00+08:00"
      }
    }
  ],
  "meta": {
    "year": 2026,
    "state": "SBH",
    "count": 1
  }
}

Without state filter, each item also includes a state_codes array.

Try in Playground

GET

/api/v1/holidays/check

Checks whether a specific date is a published holiday, optionally scoped to a state.

Parameter	Required	Allowed values	Description
date	Yes	YYYY-MM-DD	Date to check.
state	No	State code or FED	Limits the check to one state or territory.

Request

curl "https://www.malaysia-holiday.dydxsoft.my/api/v1/holidays/check?date=2026-05-30&state=SBH"

Response 200

{
  "date": "2026-05-30",
  "state_code": "SBH",
  "is_holiday": true,
  "holidays": [
    {
      "name": "Pesta Kaamatan",
      "state_codes": ["SBH"],
      "is_subject_to_change": false
    }
  ]
}

Try in Playground

State Codes

Supported regions

Use these codes in the state query parameter.

Johor JHR

Kedah KDH

Kelantan KTN

Melaka MLK

Negeri Sembilan NSN

Pahang PHG

Perak PRK

Perlis PLS

Pulau Pinang PNG

Sabah SBH

Sarawak SWK

Selangor SGR

Terengganu TRG

Wilayah Persekutuan Kuala Lumpur KUL

Wilayah Persekutuan Labuan LBN

Wilayah Persekutuan Putrajaya PJY

Errors

Response format

Validation and routing errors use the same JSON envelope.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The given data was invalid.",
    "details": {
      "year": ["The year field is required."]
    }
  },
  "errors": {
    "year": ["The year field is required."]
  }
}

Code	HTTP	Meaning
VALIDATION_ERROR	422	Request parameters failed validation.
NOT_FOUND	404	Endpoint or resource was not found.
METHOD_NOT_ALLOWED	405	HTTP method is not supported for the endpoint.