public_holidays_list

List all public holidays for a country in a given year. Returns a sorted list of holidays with their dates, English and local names, and a flag indicating whether each holiday is observed nationwide.

Holiday data is sourced from the Nager.Date public API, which covers 115+ countries.

Parameters

Parameter	Type	Required	Description
country_code	string	Yes	ISO 3166-1 alpha-2 country code, e.g. "US", "DE", or "JP".
year	integer	Yes	Calendar year to retrieve holidays for, e.g. 2026.
global_only	boolean	No	When true, only nationwide holidays are returned. Defaults to false (all holidays are returned).

Response

Field	Type	Description
country_code	string	Uppercased country code as provided, e.g. "US".
year	integer	The year that was queried.
count	integer	Number of holidays in the response (after applying the global_only filter, if set).
holidays	array	List of holiday objects (see holiday object fields below).

Holiday object

Field	Type	Description
date	string	Holiday date in YYYY-MM-DD format.
name	string	English name of the holiday.
local_name	string	Name of the holiday in the local language.
global	boolean	true when the holiday is observed nationwide; false for regional ones.

Examples

Nationwide-only holidays in Germany for 2026

{
	"country_code": "DE",
	"year": 2026,
	"global_only": true
}

Result:

{
	"country_code": "DE",
	"year": 2026,
	"count": 9,
	"holidays": [
		{
			"date": "2026-01-01",
			"name": "New Year's Day",
			"local_name": "Neujahr",
			"global": true
		},
		{
			"date": "2026-04-03",
			"name": "Good Friday",
			"local_name": "Karfreitag",
			"global": true
		},
		{
			"date": "2026-12-25",
			"name": "Christmas Day",
			"local_name": "Erster Weihnachtstag",
			"global": true
		},
		"..."
	]
}

(Truncated for brevity — the full response includes all 9 nationwide public holidays for the year.)

---

Nationwide-only holidays in the US for 2026

{
	"country_code": "US",
	"year": 2026,
	"global_only": true
}

Result:

{
	"country_code": "US",
	"year": 2026,
	"count": 10,
	"holidays": [
		{
			"date": "2026-01-01",
			"name": "New Year's Day",
			"local_name": "New Year's Day",
			"global": true
		},
		{
			"date": "2026-07-04",
			"name": "Independence Day",
			"local_name": "Independence Day",
			"global": true
		},
		"..."
	]
}

(Truncated for brevity.)

Errors

Each failure carries a precise code in the response. Argument-schema and server errors are JSON-RPC protocol errors; a rejected value is returned as a tool result with isError: true (so the agent can read the code and self-correct).

Code	When	Delivered as
invalid_arguments	An argument is missing or the wrong type.	protocol error (invalid_params)
year_out_of_range	The year is outside the supported range (1900–2100).	tool error (isError)
invalid_country	country_code is not supported by the holiday data provider.	tool error (isError)
internal_error	An unexpected server error.	protocol error (internal_error)

Notes

• Set global_only: true when you only want federally mandated or universally observed holidays, and want to exclude state, regional, or optional holidays.
• Supported country codes include US, GB, DE, FR, JP, AU, CA, BR, and 100+ others. See Nager.Date available countries for the full list.
• Holiday data is fetched from the Nager.Date API at call time and cached in memory for the lifetime of the server process. The first call for a given country and year incurs a network round-trip; subsequent calls are served from the cache.