# OpenHolidays

> Look up public holidays and school holidays for 36 countries from a workflow. List a country's public holidays for a year or a date range, get the next one coming up, check whether a date, or today, is a holiday, and count the working days between two dates with weekends and holidays taken out. School holidays are the unusual part: term breaks come back as spans of days, down to the state, canton or school zone that keeps them, so a workflow can plan around the weeks parents are away. One step also answers a date across every country at once, for a team spread over several. Names come back in any of 30 languages. Every action reads: nothing here changes anything. No account or API key required.

App · Calendars · 12 actions. Web page: https://docs.lodol.com/docs/integrations/openholidays

## Actions

### Check whether a date is a holiday

Check one date and get four plain answers: is it a public holiday, are the schools out, is it a weekend, is it a working day. Use it to gate a workflow on whether an office is open, or to hold a send that would land on a day off. It defaults to today, so 'is today a holiday' needs nothing but the country. Only Public holidays count as a day off unless you say otherwise, and anything else marked on the date is reported separately rather than silently dropped.

**Inputs**

- Country (`country`, text, required): The country to look up, chosen from the 36 countries OpenHolidays covers. The list is fetched from the API itself, so it is always current. A value from an earlier step can be a two-letter code such as 'DE' or a name such as 'Germany'.
- Date to check (`check_on`, date): The date to check. Defaults to today.
- State or region (`subdivision`, text): Narrow to one state, canton, region or municipality. Pick the country first and the list fills with what that country publishes, largest areas at the top. Leaving it empty returns the whole country. Setting it keeps the nationwide holidays plus the ones that apply there, which is the calendar someone there really keeps.
- Count these as days off (`holiday_types`, list): Which holiday types count as a day off here. Public alone by default, because that is what closes an office. A half day counts as half a day either way. One or more of: `Public` (Public: a public holiday, and a day off), `Bank` (Bank: banks and offices are closed), `Optional` (Optional: marked, but most people work). Default: `["Public"]`.
- Weekend days (`weekend_days`, list): Which days of the week are not worked. Saturday and Sunday by default. Change it for a business that trades on Saturday, otherwise the count is out by a day every week. One or more of: `Monday`, `Tuesday`, `Wednesday`, `Thursday`, `Friday`, `Saturday`, `Sunday`. Default: `["Saturday", "Sunday"]`.
- Language for names (`language`, text): The language holiday and region names come back in. English by default. Where a name has no translation in the language you pick, the original is returned rather than nothing. Default: `EN`.

**Outputs**

- `country_code` (text): The country looked up
- `country_name` (text): Its English name
- `date` (text): The date that was checked
- `holiday_types` (list): The types counted as a day off
- `is_half_day` (true/false): True when the only holiday that applies is a half day
- `is_public_holiday` (true/false): True when a public holiday of the chosen types applies
- `is_school_holiday` (true/false): True when the schools are out that day
- `is_weekend` (true/false): True when it falls on one of the weekend days
- `is_working_day` (true/false): True when it is neither a weekend day nor a day off
- `language` (text): The language the names came back in
- `other_public_holidays` (list): Public holidays on the same date the type filter left out, such as an Optional one
- `public_holiday_names` (list): Just their names
- `public_holidays` (list): The public holidays that made it a holiday
- `school_holiday_names` (list): Just their names
- `school_holidays` (list): The school holidays covering that date
- `subdivision` (text): The region filter applied, or null
- `weekday` (text): The day of the week it falls on
- `weekend_days` (list): The days treated as the weekend

**Example output**

```json
{
  "country_code": "DE",
  "country_name": "Germany",
  "date": "2026-10-03",
  "holiday_types": [
    "Public"
  ],
  "is_half_day": false,
  "is_public_holiday": true,
  "is_school_holiday": false,
  "is_weekend": true,
  "is_working_day": false,
  "language": "EN",
  "other_public_holidays": [],
  "public_holiday_names": [
    "Day of German Unity"
  ],
  "public_holidays": [
    {
      "comment": null,
      "country_code": "DE",
      "country_name": "Germany",
      "day_count": 1,
      "days_until": 19,
      "end_date": "2026-10-03",
      "ends_after_range": false,
      "group_codes": [],
      "groups": [],
      "id": "555eaa64-b8f6-44ce-850b-6af0d75555e9",
      "is_half_day": false,
      "is_single_day": true,
      "name": "Day of German Unity",
      "names_by_language": {
        "DE": "Tag der Deutschen Einheit",
        "EN": "Day of German Unity"
      },
      "nationwide": true,
      "regional_scope": "National",
      "start_date": "2026-10-03",
      "starts_before_range": false,
      "subdivision_codes": [],
      "subdivisions": [],
      "tags": [],
      "temporal_scope": "FullDay",
      "type": "Public",
      "weekday": "Saturday"
    }
  ],
  "school_holiday_names": [],
  "school_holidays": [],
  "subdivision": null,
  "weekday": "Saturday",
  "weekend_days": [
    "Saturday",
    "Sunday"
  ]
}
```

### Check which years are covered

Find out how far back and how far forward a country's holiday data reaches, for public and school holidays separately. The two rarely match: Germany's public holidays run from 2020 while its school holidays start a decade earlier. Ask this before a workflow depends on a year, because a year outside the data comes back empty rather than as an error. It is also the one-step check that the connection works.

**Inputs**

- Country (`country`, text, required): The country to look up, chosen from the 36 countries OpenHolidays covers. The list is fetched from the API itself, so it is always current. A value from an earlier step can be a two-letter code such as 'DE' or a name such as 'Germany'.
- State or region (`subdivision`, text): Narrow to one state, canton, region or municipality. Pick the country first and the list fills with what that country publishes, largest areas at the top. Leaving it empty returns the whole country. Setting it keeps the nationwide holidays plus the ones that apply there, which is the calendar someone there really keeps.
- School zone or school type (`group`, text): Narrow to one school holiday group. Four countries set different school holiday dates by language community, by region or by type of school, and this is how to pick one. The rest publish none, in which case leave it empty.

**Outputs**

- `country_code` (text): The country looked up
- `country_name` (text): Its English name
- `group` (text): The school zone or school type applied, or null
- `public_holidays` (object)
- `school_holidays` (object)
- `subdivision` (text): The region filter applied, or null

**Example output**

```json
{
  "country_code": "DE",
  "country_name": "Germany",
  "group": null,
  "public_holidays": {
    "earliest_date": "2020-01-01",
    "first_year": 2020,
    "last_year": 2030,
    "latest_date": "2030-12-26",
    "year_count": 11
  },
  "school_holidays": {
    "earliest_date": "2010-07-12",
    "first_year": 2010,
    "last_year": 2031,
    "latest_date": "2031-05-23",
    "year_count": 22
  },
  "subdivision": null
}
```

### Count working days

Count the working days between two dates, with weekends and public holidays taken out. Use it for a delivery date, an SLA window, a payroll period or a project estimate. It also hands back which holidays cost a working day and which fell at a weekend anyway. Half days count as half, and the weekend itself is a setting, so a business that trades on Saturday counts its own.

**Inputs**

- Country (`country`, text, required): The country to look up, chosen from the 36 countries OpenHolidays covers. The list is fetched from the API itself, so it is always current. A value from an earlier step can be a two-letter code such as 'DE' or a name such as 'Germany'.
- From date (`start_date`, date, required): The first day of the range, counted in.
- To date (`end_date`, date, required): The last day of the range, counted in. It must be on or after the from date, and the range can cover at most three years.
- State or region (`subdivision`, text): Narrow to one state, canton, region or municipality. Pick the country first and the list fills with what that country publishes, largest areas at the top. Leaving it empty returns the whole country. Setting it keeps the nationwide holidays plus the ones that apply there, which is the calendar someone there really keeps.
- Count these as days off (`holiday_types`, list): Which holiday types count as a day off here. Public alone by default, because that is what closes an office. A half day counts as half a day either way. One or more of: `Public` (Public: a public holiday, and a day off), `Bank` (Bank: banks and offices are closed), `Optional` (Optional: marked, but most people work). Default: `["Public"]`.
- Weekend days (`weekend_days`, list): Which days of the week are not worked. Saturday and Sunday by default. Change it for a business that trades on Saturday, otherwise the count is out by a day every week. One or more of: `Monday`, `Tuesday`, `Wednesday`, `Thursday`, `Friday`, `Saturday`, `Sunday`. Default: `["Saturday", "Sunday"]`.
- Language for names (`language`, text): The language holiday and region names come back in. English by default. Where a name has no translation in the language you pick, the original is returned rather than nothing. Default: `EN`.

**Outputs**

- `country_code` (text): The country looked up
- `country_name` (text): Its English name
- `end_date` (text): The last day of the range
- `holiday_dates` (list): Just those start dates
- `holiday_days_off` (number): Working days lost to a holiday, half counting a half
- `holiday_types` (list): The types counted as a day off
- `holidays` (list): The holidays that landed on a working day
- `holidays_on_weekends` (list): Holidays that fell at a weekend, so cost nobody a day
- `language` (text): The language the names came back in
- `start_date` (text): The first day of the range
- `subdivision` (text): The region filter applied, or null
- `total_days` (number): Every day in the range, both ends counted
- `weekend_days` (list): The days treated as the weekend
- `weekend_days_count` (number): How many fell on a weekend day
- `working_days` (number): Days that are neither weekend nor holiday; can end in .5 when a half day falls in the range

**Example output**

```json
{
  "country_code": "DE",
  "country_name": "Germany",
  "end_date": "2026-12-31",
  "holiday_dates": [
    "2026-10-03"
  ],
  "holiday_days_off": 2,
  "holiday_types": [
    "Public"
  ],
  "holidays": [
    {
      "comment": null,
      "country_code": "DE",
      "country_name": "Germany",
      "day_count": 1,
      "days_until": 19,
      "end_date": "2026-10-03",
      "ends_after_range": false,
      "group_codes": [],
      "groups": [],
      "id": "555eaa64-b8f6-44ce-850b-6af0d75555e9",
      "is_half_day": false,
      "is_single_day": true,
      "name": "Day of German Unity",
      "names_by_language": {
        "DE": "Tag der Deutschen Einheit",
        "EN": "Day of German Unity"
      },
      "nationwide": true,
      "regional_scope": "National",
      "start_date": "2026-10-03",
      "starts_before_range": false,
      "subdivision_codes": [],
      "subdivisions": [],
      "tags": [],
      "temporal_scope": "FullDay",
      "type": "Public",
      "weekday": "Saturday"
    }
  ],
  "holidays_on_weekends": [],
  "language": "EN",
  "start_date": "2026-12-01",
  "subdivision": null,
  "total_days": 31,
  "weekend_days": [
    "Saturday",
    "Sunday"
  ],
  "weekend_days_count": 8,
  "working_days": 21
}
```

### Find which countries have a public holiday

Ask one date of every country at once and get back the ones with a public holiday that day, in a single step rather than one per country. Use it to tell a global team who is off today, or to hold a send that would land on a holiday somewhere. Defaults to today, and can be narrowed to the countries you operate in.

**Inputs**

- Date (`on_date`, date): The date to ask about. Defaults to today.
- Countries (`countries`, list): Only these countries. Leave empty for every country the data covers.
- Holiday types (`holiday_types`, list): Only holidays of these types. Leave empty for every type. An Optional holiday is marked in the calendar but is a day most people work, so pick Public for the days that actually close an office. One or more of: `Public` (Public: a public holiday, and a day off), `Bank` (Bank: banks and offices are closed), `Optional` (Optional: marked, but most people work).
- How many to return (`limit`, number): How many holidays to return. Defaults to 100, which is more than any one date has. From 1 to 500. Default: `100`.
- Language for names (`language`, text): The language holiday and region names come back in. English by default. Where a name has no translation in the language you pick, the original is returned rather than nothing. Default: `EN`.

**Outputs**

- `count` (number): How many are returned
- `countries` (list): The country filter applied, empty when every country
- `country_codes` (list): The countries actually present in the result
- `country_count` (number): How many countries that is
- `date` (text): The date that was asked about
- `holiday_types` (list): The type filter applied, empty when every type is kept
- `holidays` (list)
- `language` (text): The language the names came back in
- `matched_count` (number): How many matched before the limit
- `total_count` (number): How many the date held before filtering
- `weekday` (text): The day of the week it falls on

**Example output**

```json
{
  "count": 1,
  "countries": [
    "DE"
  ],
  "country_codes": [
    "DE"
  ],
  "country_count": 1,
  "date": "2026-10-03",
  "holiday_types": [],
  "holidays": [
    {
      "comment": null,
      "country_code": "DE",
      "country_name": "Germany",
      "day_count": 1,
      "days_until": 19,
      "end_date": "2026-10-03",
      "ends_after_range": false,
      "group_codes": [],
      "groups": [],
      "id": "555eaa64-b8f6-44ce-850b-6af0d75555e9",
      "is_half_day": false,
      "is_single_day": true,
      "name": "Day of German Unity",
      "names_by_language": {
        "DE": "Tag der Deutschen Einheit",
        "EN": "Day of German Unity"
      },
      "nationwide": true,
      "regional_scope": "National",
      "start_date": "2026-10-03",
      "starts_before_range": false,
      "subdivision_codes": [],
      "subdivisions": [],
      "tags": [],
      "temporal_scope": "FullDay",
      "type": "Public",
      "weekday": "Saturday"
    }
  ],
  "language": "EN",
  "matched_count": 1,
  "total_count": 34,
  "weekday": "Saturday"
}
```

### Find which countries have schools out

Ask one date of every country at once and get back the ones whose schools are closed that day. School holidays are staggered across Europe, so this is how to see, in one step, which offices will be thin on the ground in a given week. Defaults to today, and can be narrowed to the countries you operate in.

**Inputs**

- Date (`on_date`, date): The date to ask about. Defaults to today.
- Countries (`countries`, list): Only these countries. Leave empty for every country the data covers.
- What to include (`holiday_types`, list): Which of the things a school calendar marks to include. Leave it empty for all of them. Alongside the holidays themselves, a few countries mark the day term starts and the day lessons end. One or more of: `School` (School holidays: the schools are closed), `BackToSchool` (Back to school: the term starts), `EndOfLessons` (End of lessons: the term ends).
- How many to return (`limit`, number): How many entries to return. Defaults to 100. A summer date can have more, so raise it for a July run. From 1 to 500. Default: `100`.
- Language for names (`language`, text): The language holiday and region names come back in. English by default. Where a name has no translation in the language you pick, the original is returned rather than nothing. Default: `EN`.

**Outputs**

- `count` (number): How many are returned
- `countries` (list): The country filter applied, empty when every country
- `country_codes` (list): The countries actually present in the result
- `country_count` (number): How many countries that is
- `date` (text): The date that was asked about
- `holiday_types` (list): The type filter applied, empty when every type is kept
- `holidays` (list)
- `language` (text): The language the names came back in
- `matched_count` (number): How many matched before the limit
- `total_count` (number): How many the date held before filtering
- `weekday` (text): The day of the week it falls on

**Example output**

```json
{
  "count": 1,
  "countries": [
    "DE"
  ],
  "country_codes": [
    "DE"
  ],
  "country_count": 1,
  "date": "2025-12-24",
  "holiday_types": [],
  "holidays": [
    {
      "comment": null,
      "country_code": "DE",
      "country_name": "Germany",
      "day_count": 15,
      "days_until": -266,
      "end_date": "2026-01-05",
      "ends_after_range": false,
      "group_codes": [],
      "groups": [],
      "id": "fae75443-4eb3-4720-9ba2-3dcca3553820",
      "is_half_day": false,
      "is_single_day": false,
      "name": "Christmas Holidays",
      "names_by_language": {
        "EN": "Christmas Holidays"
      },
      "nationwide": false,
      "regional_scope": "Regional",
      "start_date": "2025-12-22",
      "starts_before_range": true,
      "subdivision_codes": [
        "DE-BY"
      ],
      "subdivisions": [
        {
          "code": "DE-BY",
          "short_name": "BY"
        }
      ],
      "tags": [],
      "temporal_scope": "FullDay",
      "type": "School",
      "weekday": "Monday"
    }
  ],
  "language": "EN",
  "matched_count": 1,
  "total_count": 68,
  "weekday": "Wednesday"
}
```

### Get the next public holiday

Get the single next public holiday in a country, returned flat so a later step can read the name, the date and how many days away it is without indexing into a list. Answers 'when is the next day off' in one step, so a scheduled workflow can act a fortnight before one. If nothing falls in the year ahead it returns found = false rather than failing.

**Inputs**

- Country (`country`, text, required): The country to look up, chosen from the 36 countries OpenHolidays covers. The list is fetched from the API itself, so it is always current. A value from an earlier step can be a two-letter code such as 'DE' or a name such as 'Germany'.
- State or region (`subdivision`, text): Narrow to one state, canton, region or municipality. Pick the country first and the list fills with what that country publishes, largest areas at the top. Leaving it empty returns the whole country. Setting it keeps the nationwide holidays plus the ones that apply there, which is the calendar someone there really keeps.
- Counting from (`from_date`, date): The date to start looking from. Defaults to today.
- Count these as days off (`holiday_types`, list): Which holiday types count as a day off here. Public alone by default, because that is what closes an office. A half day counts as half a day either way. One or more of: `Public` (Public: a public holiday, and a day off), `Bank` (Bank: banks and offices are closed), `Optional` (Optional: marked, but most people work). Default: `["Public"]`.
- Nationwide holidays only (`nationwide_only`, true/false): Keep only the holidays that apply to the whole country, dropping the ones limited to particular states or regions. Off by default. Default: `false`.
- Language for names (`language`, text): The language holiday and region names come back in. English by default. Where a name has no translation in the language you pick, the original is returned rather than nothing. Default: `EN`.

**Outputs**

- `counted_from` (text): The date the search started from
- `country_code` (text): The country looked up
- `country_name` (text): Its English name
- `day_count` (number): How many days it runs for
- `days_until` (number): Days from the date it was counted from
- `end_date` (text): The last day
- `found` (true/false): False when nothing falls in the window
- `holiday_types` (list): The types counted as a day off
- `id` (text): The holiday's stable id
- `is_half_day` (true/false): True when only half the day is off
- `is_single_day` (true/false): True when it starts and ends on the same day
- `language` (text): The language the name came back in
- `name` (text): The name, in the language that was asked for
- `names_by_language` (object): Every translation published, keyed by language code
- `nationwide` (true/false): True when it applies to the whole country
- `start_date` (text): The first day, as YYYY-MM-DD
- `subdivision` (text): The region filter applied, or null
- `subdivision_codes` (list): Where it applies when it is not nationwide
- `type` (text): Public, Bank or Optional
- `weekday` (text): The day of the week
- `window_days` (number): How far ahead it looked, in days

**Example output**

```json
{
  "counted_from": "2026-09-14",
  "country_code": "DE",
  "country_name": "Germany",
  "day_count": 1,
  "days_until": 19,
  "end_date": "2026-10-03",
  "found": true,
  "holiday_types": [
    "Public"
  ],
  "id": "555eaa64-b8f6-44ce-850b-6af0d75555e9",
  "is_half_day": false,
  "is_single_day": true,
  "language": "EN",
  "name": "Day of German Unity",
  "names_by_language": {
    "DE": "Tag der Deutschen Einheit",
    "EN": "Day of German Unity"
  },
  "nationwide": true,
  "start_date": "2026-10-03",
  "subdivision": null,
  "subdivision_codes": [],
  "type": "Public",
  "weekday": "Saturday",
  "window_days": 366
}
```

### List a country's regions

List the states, cantons, regions or municipalities a country publishes holidays for, largest areas first. Use it to find the code a region filter wants, or to see how far down a country's calendar varies: Germany stops at its sixteen federal states, Switzerland reaches individual municipalities. Each region carries its ISO 3166-2 code too, which is not always the same as the code this API answers to.

**Inputs**

- Country (`country`, text, required): The country to look up, chosen from the 36 countries OpenHolidays covers. The list is fetched from the API itself, so it is always current. A value from an earlier step can be a two-letter code such as 'DE' or a name such as 'Germany'.
- Search for (`search`, text): Only regions whose name or code contains this text. Case and accents are ignored.
- Largest areas only (`top_level_only`, true/false): Keep only a country's largest areas, dropping the districts and municipalities inside them. Useful for a country like Switzerland, which publishes 26 cantons and nearly 2,000 places within them. Default: `false`.
- Language for names (`language`, text): The language holiday and region names come back in. English by default. Where a name has no translation in the language you pick, the original is returned rather than nothing. Default: `EN`.

**Outputs**

- `count` (number): How many are returned
- `country_code` (text): The country looked up
- `country_name` (text): Its English name
- `language` (text): The language the names came back in
- `region_codes` (list): Just the codes, ready to feed a later step
- `regions` (list): One entry per region, largest areas first
- `search` (text): The search that was applied
- `top_level_count` (number): How many of the returned regions are top level
- `total_count` (number): How many the country publishes before filtering

**Example output**

```json
{
  "count": 2,
  "country_code": "DE",
  "country_name": "Germany",
  "language": "EN",
  "region_codes": [
    "DE-BY",
    "DE-BY-AU"
  ],
  "regions": [
    {
      "category": "federal state",
      "code": "DE-BY",
      "depth": 0,
      "group_codes": [],
      "iso_code": "DE-BY",
      "name": "Bavaria",
      "official_languages": [
        "DE"
      ],
      "parent_path": [],
      "short_name": "BY"
    },
    {
      "category": "municipality",
      "code": "DE-BY-AU",
      "depth": 1,
      "group_codes": [],
      "iso_code": null,
      "name": "Augsburg",
      "official_languages": [
        "DE"
      ],
      "parent_path": [
        "Bavaria"
      ],
      "short_name": "BY-AU"
    }
  ],
  "search": null,
  "top_level_count": 1,
  "total_count": 17
}
```

### List countries

List every country OpenHolidays has holiday data for, with its ISO 3166-1 code and official languages, sorted by name. This is the same list every country dropdown here is built from, and the way to check whether somewhere is covered before a workflow depends on it. Coverage is 36 countries, mostly European. Search it by name or by code.

**Inputs**

- Search for (`search`, text): Only countries whose name or code contains this text. Case and accents are ignored, and names in every language are searched. Leave empty for all of them.
- How many to return (`limit`, number): How many countries to return. Every match is returned unless you set this. From 1 to 1000.

**Outputs**

- `count` (number): How many are returned
- `countries` (list): One entry per country, sorted by name
- `country_codes` (list): Just the codes, ready to feed a later step
- `matched_count` (number): How many matched a search
- `search` (text): The search that was applied
- `total_count` (number): How many countries are covered in all

**Example output**

```json
{
  "count": 2,
  "countries": [
    {
      "country_code": "DE",
      "name": "Germany",
      "names_by_language": {
        "EN": "Germany"
      },
      "official_languages": [
        "DE"
      ]
    },
    {
      "country_code": "CH",
      "name": "Switzerland",
      "names_by_language": {
        "EN": "Switzerland"
      },
      "official_languages": [
        "DE",
        "FR",
        "IT"
      ]
    }
  ],
  "country_codes": [
    "DE",
    "CH"
  ],
  "matched_count": 2,
  "search": null,
  "total_count": 36
}
```

### List languages

List the languages OpenHolidays publishes holiday names in, with their ISO 639-1 codes. Useful when a workflow has to write to people in their own language: pick the code here, then set it as the language on any other action. Not every holiday is translated into every language, and where one is not the original name is returned rather than a blank.

**Inputs**

- Search for (`search`, text): Only languages whose name or code contains this text. Leave empty for all of them.

**Outputs**

- `count` (number): How many are returned
- `language_codes` (list): Just the codes, ready to feed a later step
- `languages` (list): One entry per language, sorted by name
- `search` (text): The search that was applied
- `total_count` (number): How many languages are published in all

**Example output**

```json
{
  "count": 2,
  "language_codes": [
    "DE",
    "EN"
  ],
  "languages": [
    {
      "language_code": "DE",
      "name": "German",
      "names_by_language": {
        "EN": "German"
      }
    },
    {
      "language_code": "EN",
      "name": "English",
      "names_by_language": {
        "EN": "English"
      }
    }
  ],
  "search": null,
  "total_count": 30
}
```

### List public holidays

List a country's public holidays. Leave the dates empty for this calendar year, or set them for a quarter, a sprint or any window up to three years. Each holiday comes back with its date, the weekday, whether it applies nationwide and which regions it applies in. Choosing a state or canton keeps that region's own holidays alongside the national ones, which is the calendar someone working there actually keeps.

**Inputs**

- Country (`country`, text, required): The country to look up, chosen from the 36 countries OpenHolidays covers. The list is fetched from the API itself, so it is always current. A value from an earlier step can be a two-letter code such as 'DE' or a name such as 'Germany'.
- From date (`start_date`, date): The first day of the range, counted in. Leave both dates empty for the current calendar year.
- To date (`end_date`, date): The last day of the range, counted in. It must be on or after the from date, and the range can cover at most three years.
- State or region (`subdivision`, text): Narrow to one state, canton, region or municipality. Pick the country first and the list fills with what that country publishes, largest areas at the top. Leaving it empty returns the whole country. Setting it keeps the nationwide holidays plus the ones that apply there, which is the calendar someone there really keeps.
- Holiday types (`holiday_types`, list): Only holidays of these types. Leave empty for every type. An Optional holiday is marked in the calendar but is a day most people work, so pick Public for the days that actually close an office. One or more of: `Public` (Public: a public holiday, and a day off), `Bank` (Bank: banks and offices are closed), `Optional` (Optional: marked, but most people work).
- Nationwide holidays only (`nationwide_only`, true/false): Keep only the holidays that apply to the whole country, dropping the ones limited to particular states or regions. Off by default. Default: `false`.
- Name contains (`name_contains`, text): Only holidays whose name contains this text. Case and accents are ignored, and every language the name is published in is searched, so 'weihnachten' finds Christmas in a German calendar asked for in English.
- Language for names (`language`, text): The language holiday and region names come back in. English by default. Where a name has no translation in the language you pick, the original is returned rather than nothing. Default: `EN`.

**Outputs**

- `count` (number): How many are returned
- `country_code` (text): The country looked up
- `country_name` (text): Its English name
- `dates` (list): Just the start dates, ready to feed a later step
- `days_in_range` (number): How many days the range covers
- `end_date` (text): The last day of the range
- `holiday_types` (list): The type filter applied, empty when every type is kept
- `holidays` (list)
- `language` (text): The language the names came back in
- `name_contains` (text): The name filter applied, or null
- `nationwide_only` (true/false): Whether regional holidays were dropped
- `start_date` (text): The first day of the range
- `subdivision` (text): The region filter applied, or null
- `total_count` (number): How many the range held before filtering

**Example output**

```json
{
  "count": 2,
  "country_code": "DE",
  "country_name": "Germany",
  "dates": [
    "2026-01-06",
    "2026-10-03"
  ],
  "days_in_range": 365,
  "end_date": "2026-12-31",
  "holiday_types": [
    "Public"
  ],
  "holidays": [
    {
      "comment": null,
      "country_code": "DE",
      "country_name": "Germany",
      "day_count": 1,
      "days_until": -251,
      "end_date": "2026-01-06",
      "ends_after_range": false,
      "group_codes": [],
      "groups": [],
      "id": "7f99caaa-1eb2-4564-a6e8-13844634c929",
      "is_half_day": false,
      "is_single_day": true,
      "name": "Epiphany",
      "names_by_language": {
        "DE": "Heilige Drei Koenige",
        "EN": "Epiphany"
      },
      "nationwide": false,
      "regional_scope": "Regional",
      "start_date": "2026-01-06",
      "starts_before_range": false,
      "subdivision_codes": [
        "DE-BW",
        "DE-BY",
        "DE-ST"
      ],
      "subdivisions": [
        {
          "code": "DE-BW",
          "short_name": "BW"
        },
        {
          "code": "DE-BY",
          "short_name": "BY"
        },
        {
          "code": "DE-ST",
          "short_name": "ST"
        }
      ],
      "tags": [],
      "temporal_scope": "FullDay",
      "type": "Public",
      "weekday": "Tuesday"
    },
    {
      "comment": null,
      "country_code": "DE",
      "country_name": "Germany",
      "day_count": 1,
      "days_until": 19,
      "end_date": "2026-10-03",
      "ends_after_range": false,
      "group_codes": [],
      "groups": [],
      "id": "555eaa64-b8f6-44ce-850b-6af0d75555e9",
      "is_half_day": false,
      "is_single_day": true,
      "name": "Day of German Unity",
      "names_by_language": {
        "DE": "Tag der Deutschen Einheit",
        "EN": "Day of German Unity"
      },
      "nationwide": true,
      "regional_scope": "National",
      "start_date": "2026-10-03",
      "starts_before_range": false,
      "subdivision_codes": [],
      "subdivisions": [],
      "tags": [],
      "temporal_scope": "FullDay",
      "type": "Public",
      "weekday": "Saturday"
    }
  ],
  "language": "EN",
  "name_contains": null,
  "nationwide_only": false,
  "start_date": "2026-01-01",
  "subdivision": null,
  "total_count": 20
}
```

### List school holiday groups

List the zones and school types a country splits its school holidays by. Belgium sets its by language community, the Netherlands by region, and Switzerland and Germany by type of school, so primary and vocational schools break on different days. This is how to find the code for one. The other 32 countries publish none, and an empty result is the normal answer for them rather than a fault; where a country staggers school holidays by zone, as France does, the zones are regions instead and 'List a country's regions' finds them.

**Inputs**

- Country (`country`, text, required): The country to look up, chosen from the 36 countries OpenHolidays covers. The list is fetched from the API itself, so it is always current. A value from an earlier step can be a two-letter code such as 'DE' or a name such as 'Germany'.
- State or region (`subdivision`, text): Narrow to one state, canton, region or municipality. Pick the country first and the list fills with what that country publishes, largest areas at the top. Leaving it empty returns the whole country. Setting it keeps the nationwide holidays plus the ones that apply there, which is the calendar someone there really keeps.
- Language for names (`language`, text): The language holiday and region names come back in. English by default. Where a name has no translation in the language you pick, the original is returned rather than nothing. Default: `EN`.

**Outputs**

- `count` (number): How many there are
- `country_code` (text): The country looked up
- `country_name` (text): Its English name
- `group_codes` (list): Just the codes, ready to feed a later step
- `groups` (list): One entry per group, empty for most countries
- `language` (text): The language the names came back in
- `subdivision` (text): The region filter applied, or null

**Example output**

```json
{
  "count": 2,
  "country_code": "DE",
  "country_name": "Germany",
  "group_codes": [
    "DE-MV-ABS",
    "DE-MV-BBS"
  ],
  "groups": [
    {
      "category": "school type",
      "code": "DE-MV-ABS",
      "comment": null,
      "depth": 0,
      "name": "General Schools",
      "short_name": "MV-ABS",
      "subdivision_codes": [
        "DE-MV"
      ]
    },
    {
      "category": "school type",
      "code": "DE-MV-BBS",
      "comment": null,
      "depth": 0,
      "name": "Vocational Schools",
      "short_name": "MV-BBS",
      "subdivision_codes": [
        "DE-MV"
      ]
    }
  ],
  "language": "EN",
  "subdivision": null
}
```

### List school holidays

List a country's school holidays, which is the thing almost no holiday API publishes. Each one is a span of days rather than a single date, so a fortnight of Easter holidays comes back as one entry with its start, its end and how many days it runs. Term dates vary by region and, in a few countries, by zone or type of school, so pick those to get the dates a particular school really keeps. Use it to plan around the weeks parents will be taking off.

**Inputs**

- Country (`country`, text, required): The country to look up, chosen from the 36 countries OpenHolidays covers. The list is fetched from the API itself, so it is always current. A value from an earlier step can be a two-letter code such as 'DE' or a name such as 'Germany'.
- From date (`start_date`, date): The first day of the range, counted in. Leave both dates empty for the current calendar year.
- To date (`end_date`, date): The last day of the range, counted in. It must be on or after the from date, and the range can cover at most three years.
- State or region (`subdivision`, text): Narrow to one state, canton, region or municipality. Pick the country first and the list fills with what that country publishes, largest areas at the top. Leaving it empty returns the whole country. Setting it keeps the nationwide holidays plus the ones that apply there, which is the calendar someone there really keeps.
- School zone or school type (`group`, text): Narrow to one school holiday group. Four countries set different school holiday dates by language community, by region or by type of school, and this is how to pick one. The rest publish none, in which case leave it empty.
- What to include (`holiday_types`, list): Which of the things a school calendar marks to include. Leave it empty for all of them. Alongside the holidays themselves, a few countries mark the day term starts and the day lessons end. One or more of: `School` (School holidays: the schools are closed), `BackToSchool` (Back to school: the term starts), `EndOfLessons` (End of lessons: the term ends).
- Name contains (`name_contains`, text): Only holidays whose name contains this text. Case and accents are ignored, and every language the name is published in is searched, so 'weihnachten' finds Christmas in a German calendar asked for in English.
- Language for names (`language`, text): The language holiday and region names come back in. English by default. Where a name has no translation in the language you pick, the original is returned rather than nothing. Default: `EN`.

**Outputs**

- `count` (number): How many are returned
- `country_code` (text): The country looked up
- `country_name` (text): Its English name
- `dates` (list): Just the start dates, ready to feed a later step
- `days_in_range` (number): How many days the range covers
- `end_date` (text): The last day of the range
- `group` (text): The school zone or school type applied, or null
- `holiday_types` (list): The type filter applied, empty when every type is kept
- `holidays` (list)
- `language` (text): The language the names came back in
- `name_contains` (text): The name filter applied, or null
- `start_date` (text): The first day of the range
- `subdivision` (text): The region filter applied, or null
- `total_count` (number): How many the range held before filtering
- `total_days_off` (number): The days off across all of them added up

**Example output**

```json
{
  "count": 1,
  "country_code": "DE",
  "country_name": "Germany",
  "dates": [
    "2025-12-22"
  ],
  "days_in_range": 365,
  "end_date": "2026-12-31",
  "group": null,
  "holiday_types": [
    "School"
  ],
  "holidays": [
    {
      "comment": null,
      "country_code": "DE",
      "country_name": "Germany",
      "day_count": 15,
      "days_until": -266,
      "end_date": "2026-01-05",
      "ends_after_range": false,
      "group_codes": [],
      "groups": [],
      "id": "fae75443-4eb3-4720-9ba2-3dcca3553820",
      "is_half_day": false,
      "is_single_day": false,
      "name": "Christmas Holidays",
      "names_by_language": {
        "EN": "Christmas Holidays"
      },
      "nationwide": false,
      "regional_scope": "Regional",
      "start_date": "2025-12-22",
      "starts_before_range": true,
      "subdivision_codes": [
        "DE-BY"
      ],
      "subdivisions": [
        {
          "code": "DE-BY",
          "short_name": "BY"
        }
      ],
      "tags": [],
      "temporal_scope": "FullDay",
      "type": "School",
      "weekday": "Monday"
    }
  ],
  "language": "EN",
  "name_contains": null,
  "start_date": "2026-01-01",
  "subdivision": "DE-BY",
  "total_count": 8,
  "total_days_off": 15
}
```