GET /v1/holidays
List all holidays for a country and year.
| Name | Type | Required | Description |
|---|
country | string | Yes | ISO 3166-1 alpha-2 country code. Case-insensitive. |
year | integer | Yes | Must be 2025, 2026, or 2027. Required in the REST API. |
region | string | No | ISO 3166-2 subdivision suffix. Requires paid plan. Regional holidays are only included when this is supplied. |
curl -X GET "https://jday-api.jday.workers.dev/v1/holidays?country=JP&year=2026" \
-H "Authorization: Bearer jday_live_xxx" \
-H "Accept: application/json"
{
"country": "JP",
"year": 2026,
"region": null,
"holidays": [
{
"date": "2026-01-01",
"official_date": null,
"name": "New Year's Day",
"local_name": "元日",
"type": "public",
"date_accuracy": "exact"
},
{
"date": "2026-01-12",
"official_date": null,
"name": "Coming of Age Day",
"local_name": "成人の日",
"type": "public",
"date_accuracy": "exact"
}
]
}
| Field | Type | Description |
|---|
country | string | Normalized country code. |
year | integer | The requested year. |
region | string | null | Region code if provided, otherwise null. |
holidays | array | All holidays for this country/year/region. Sorted by date, then name. |
| Field | Type | Description |
|---|
date | string | Effective non-working date (what the engine uses). |
official_date | string | null | Legal date when different from date, otherwise null. |
name | string | English display name. |
local_name | string | null | Localized name when available, otherwise null. |
type | string | "public" or "regional". |
date_accuracy | string | "exact" or "estimated". |
year is required in the REST API. Missing year returns 400 missing_parameter.- The MCP server may default to the current UTC year as a convenience, but the REST API does not.
- Regional holidays are only included when a valid
region parameter is supplied.
local_name is always present (as null when unavailable).date_accuracy is present on every entry.
| Condition | Error |
|---|
Missing country or year | 400 missing_parameter |
| Malformed or unsupported year | 400 invalid_year |
| Unknown country | 400 invalid_country |
| Invalid region | 400 invalid_region |
| Region on Free plan | 403 plan_upgrade_required |