public_holidays_in_range

List all public holidays in a country between two dates (inclusive). Useful for calculating working days, planning travel, or checking whether a date window spans any public holidays.

Holiday data is sourced from the Nager.Date public API, which covers 115+ countries. Date ranges that span multiple calendar years are handled correctly.

Parameters

Parameter	Type	Required	Description
country_code	string	Yes	ISO 3166-1 alpha-2 country code, e.g. "FR", "GB", or "AU".
start	string	Yes	Start of the date range (inclusive), ISO 8601 format, e.g. "2026-06-01".
end	string	Yes	End of the date range (inclusive), ISO 8601 format, e.g. "2026-12-31".
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. "FR".
start	string	Start of the queried range as provided.
end	string	End of the queried range as provided.
count	integer	Number of holidays found within the range (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

Holidays in France in the second half of 2026

{
	"country_code": "FR",
	"start": "2026-06-01",
	"end": "2026-12-31"
}

Result:

{
	"country_code": "FR",
	"start": "2026-06-01",
	"end": "2026-12-31",
	"count": 5,
	"holidays": [
		{
			"date": "2026-07-14",
			"name": "Bastille Day",
			"local_name": "Fête nationale",
			"global": true
		},
		{
			"date": "2026-08-15",
			"name": "Assumption Day",
			"local_name": "Assomption",
			"global": true
		},
		{
			"date": "2026-11-01",
			"name": "All Saints' Day",
			"local_name": "Toussaint",
			"global": true
		},
		{
			"date": "2026-11-11",
			"name": "Armistice Day",
			"local_name": "Armistice 1918",
			"global": true
		},
		{
			"date": "2026-12-25",
			"name": "Christmas Day",
			"local_name": "Noël",
			"global": true
		}
	]
}

---

Check if a two-week window in the UK contains any public holidays

{
	"country_code": "GB",
	"start": "2026-08-24",
	"end": "2026-09-06"
}

Result:

{
	"country_code": "GB",
	"start": "2026-08-24",
	"end": "2026-09-06",
	"count": 1,
	"holidays": [
		{
			"date": "2026-08-31",
			"name": "Summer Bank Holiday",
			"local_name": "Summer Bank Holiday",
			"global": false
		}
	]
}

---

Range spanning two years (year-end planning)

{
	"country_code": "US",
	"start": "2026-12-20",
	"end": "2027-01-10",
	"global_only": true
}

Result:

{
	"country_code": "US",
	"start": "2026-12-20",
	"end": "2027-01-10",
	"count": 2,
	"holidays": [
		{
			"date": "2026-12-25",
			"name": "Christmas Day",
			"local_name": "Christmas Day",
			"global": true
		},
		{
			"date": "2027-01-01",
			"name": "New Year's Day",
			"local_name": "New Year's Day",
			"global": true
		}
	]
}

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)
invalid_date_range	start is after end.	tool error (isError)
invalid_datetime	start or end is not a valid ISO 8601 date.	tool error (isError)
year_out_of_range	The start or end 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

• Both start and end are inclusive — a holiday that falls exactly on either boundary date is included in the result.
• Ranges that span multiple calendar years are handled correctly: holiday data is fetched for each year individually and then filtered to the requested range.
• Set global_only: true to exclude state, regional, or optional observances and retain only federally mandated or universally observed 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.