Public holidays
get_holidaysList public holidays for a country, an optional ISO 3166-2 region, or a city. Use when the user asks whether a date is a holiday somewhere, or which days are holidays in a year. Pass one year, a list of years so 2026, 2027, and 2028 can come back together, or a date range. Each holiday has the date, the weekday, whether it falls on Saturday or Sunday, whether it creates a long weekend of three or more days with Saturday and Sunday, the local name, the English name, whether it is regional, the region codes, the file it came from, and the calendar page URL. The same holiday list marks the planner timeline.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| city | No | Optional city. Its country and region are used. City name or a city id from a city search. Spelling and accents are flexible. When several cities share a name, the best match from the site search is used and the others come back in alternatives. | |
| year | No | One calendar year. Defaults to the current year when years, start_date, and end_date are omitted. Do not pass year and years together. | |
| years | No | Calendar years, such as [2026, 2027, 2028]. A gap is not filled in. Do not pass years with year or with a date range. | |
| region | No | Optional ISO 3166-2 code, such as DE-BY or GB-SCT. National holidays are included with that region's own days. | |
| country | No | ISO 3166-1 alpha-2 code or English country name. UK is accepted for the United Kingdom. | |
| end_date | No | Last day, YYYY-MM-DD. | |
| start_date | No | First day, YYYY-MM-DD. Use with end_date instead of year. At most 366 days. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| city | Yes | ||
| year | Yes | ||
| error | No | ||
| years | Yes | ||
| region | Yes | ||
| source | Yes | ||
| country | Yes | ||
| end_date | Yes | ||
| holidays | Yes | ||
| candidates | No | ||
| start_date | Yes | ||
| alternatives | No | Other cities that matched the same name, after the best-ranked city was chosen. The order is the site search order: match, then priority, then population. | |
| country_name | Yes |