---
title: "OpenHolidays API"
description: "Free OpenHolidays API in TapHome, no API key: public holiday, school holiday and weekend flags for 35+ countries to drive heating and alarm schedules."
url: "https://taphome.com/en/compatibility/openholidays/"
language: en
lastmod: 2026-10-08
generator: hugo
ai:
  topics: ["http","other","rest-api","holiday-detection","scheduling"]
  questions: ["How to integrate OpenHolidays API with TapHome?","How does TapHome detect public holidays automatically?","How to configure country and region codes for OpenHolidays in TapHome?","Why does the public holiday device show incorrect results?","What is the difference between IsPublicHoliday and IsSchoolHoliday in TapHome?","Can TapHome adjust heating schedules based on holidays?"]
---

# OpenHolidays API

Communication: Packet Parser → HTTP

- [OpenHolidays API Website](https://www.openholidaysapi.org)

## Integration guide

The OpenHolidays API is a free, open-source REST API that provides public holiday and school holiday data for over 35 countries. TapHome connects to this cloud service over HTTPS using a PacketParser HTTP template — no authentication or API key is required.

The template provides three read-only boolean devices: one for public holidays, one for school holidays, and one for weekends. These can be used in TapHome smart rules to adjust heating schedules, alarm modes, lighting scenes, or any other automation based on whether today is a working day or not.

The template was created by ToBo, a community contributor.

## Configuration

During template import, two parameters are required:

- **Country** — ISO 3166-1 alpha-2 country code (e.g., `SK` for Slovakia, `DE` for Germany, `CZ` for Czechia). The full list of supported countries is available at `https://openholidaysapi.org/Countries`.
- **Region** — ISO 3166-2 subdivision code (e.g., `SK-BC` for Banská Bystrica region, `DE-BY` for Bavaria). The list of subdivisions for a given country is available at `https://openholidaysapi.org/Subdivisions?countryIsoCode={CountryCode}`.

Both parameters are stored as Module Variables in TapHome and can be changed after import without re-importing the template.

> [!TIP]
> Many countries have region-specific public holidays. If holiday detection seems incorrect, verify that the subdivision code matches the correct region — not just the country code.

## Device capabilities

### Public holiday detection

The Public Holiday device queries the `GET /PublicHolidays` endpoint once per hour. It sends today's date along with the configured country and region codes. If the API returns a holiday entry for that date, the device shows **Yes**; otherwise it shows **No**.

### School holiday detection

The School Holiday device works the same way but queries the `GET /SchoolHolidays` endpoint. It detects whether today falls within a school vacation period for the configured country and region.

> [!NOTE]
> School holiday data availability varies by country. Some countries have limited subdivision coverage — check the API documentation to verify that your region is supported.

### Weekend detection

The Weekend device does not call the API. It uses TapHome's local `NOW().DAYOFWEEK` function to determine whether today is Saturday (day 6) or Sunday (day 0). This device works independently of the API and does not require an internet connection.

### Additional capabilities

The OpenHolidays API also exposes endpoints for querying holidays by a specific date across all countries (`/PublicHolidaysByDate`, `/SchoolHolidaysByDate`), listing supported countries and regional subdivisions, and retrieving statistics about available data ranges. These can be added in a future template update.

## Troubleshooting

### Holiday detection returns incorrect results

1. Verify the Country code is correct — use the `/Countries` endpoint to check the list of supported countries
2. Verify the Region (subdivision) code — some public holidays are region-specific and will not appear with the wrong subdivision code
3. Check the API directly in a browser: `https://openholidaysapi.org/PublicHolidays?countryIsoCode=SK&subdivisionCode=SK-BC&validFrom=2026-01-01&validTo=2026-01-01` — replace the date and codes with your values
4. If the API returns an empty array `[]` for a date that should be a holiday, the data may not yet be available for that country or year

### Device shows error (NaN)

If the API is unreachable (network issue, DNS failure, or API downtime), the template returns NaN with the HTTP status code in the error message. The OpenHolidays API is a community project with no SLA — check the status page at `https://openpotato.github.io/uptime/` for current availability.

> [!WARNING]
> The OpenHolidays API is a community-maintained open data project. While it has been reliably available, there is no uptime guarantee. For mission-critical automations, consider adding a fallback rule that handles the error state gracefully.

## Available devices 3

These devices appear in TapHome after import.

OpenHolidays Module

Custom Variables

`Country` (string) ISO 3166-1 alpha-2 country code (e.g. SK, DE, CZ)

Full list at openholidaysapi.org/Countries

`Region` (string) ISO 3166-2 subdivision code (e.g. SK-BC, DE-BY)

List at openholidaysapi.org/Subdivisions?countryIsoCode={CountryCode}

Public Holiday Switch Read-only

Queries the OpenHolidays API once per hour — Yes if today is a public holiday for the configured country and region, No otherwise

boolean json\_path

Values / States: Yes · No

Read switch state

```taphome
var dt := NOW();
var date := dt.YEAR + "-" + dt.MONTH + "-" + dt.DAY;
var req:= "PublicHolidays?countryIsoCode=" + Country + "&subdivisionCode=" + Region + "&validFrom="+date + "&validTo="+date;
var response := SENDHTTPREQUEST(req);

if response.IsSuccess
  var content := response.Content;
  var isHoliday := PARSEJSON( content, "[0].temporalScope", 1);
  if isHoliday != null
    return(1);
  else
    return(0);
  end
else
  adderror(response.StatusCode + " (" + response.ReasonPhrase + ")");
  return(NaN);
end
```

School Holiday Switch Read-only

Queries the OpenHolidays API once per hour — Yes if today falls within a school holiday period for the configured country and region, No otherwise

boolean json\_path

Values / States: Yes · No

Read switch state

```taphome
var dt := NOW();
var date := dt.YEAR + "-" + dt.MONTH + "-" + dt.DAY;
var req:= "SchoolHolidays?countryIsoCode=" + Country + "&subdivisionCode=" + Region + "&validFrom="+date + "&validTo="+date;
var response := SENDHTTPREQUEST(req);

if response.IsSuccess
  var content := response.Content;
  var isHoliday := PARSEJSON( content, "[0].temporalScope", 1);
  if isHoliday != null
    return(1);
  else
    return(0);
  end
else
  adderror(response.StatusCode + " (" + response.ReasonPhrase + ")");
  return(NaN);
end
```

Weekend Switch Read-only

Local calculation — Yes on Saturday and Sunday, No on weekdays. Does not use the API.

boolean

Values / States: Yes · No

Read switch state

```taphome
var dt := NOW();
return(dt.DAYOFWEEK = 0 or dt.DAYOFWEEK = 6);
```

**Connection:** Packet Parser → HTTP

Possible improvements (7)

- Public Holidays By Date — Returns all public holidays across all countries for a single date — alternative to country-scoped query
- School Holidays By Date — Returns all school holidays across all countries for a single date
- Supported Countries — List of 35+ supported countries — useful for configuration but not a sensor
- Regional Subdivisions — List of regional divisions for a country — useful for configuration
- Public Holiday Data Range — Date range of available public holiday data for a country
- School Holiday Data Range — Date range of available school holiday data for a country
- Holiday Groups — Non-geographic holiday groupings (language zones, school types) for a country

## Import parameters

Enter these values when you import the XML.

| Asked in the app | Default |
|------------------|---------|
| Country          | `SK`    |
| Region           | `SK-BC` |

## Sources

- OpenHolidays API Reference (OpenAPI)
  
  [openholidaysapi.org](https://openholidaysapi.org/swagger/v1/swagger.json) 2026-03-28
- OpenHolidays API — Website Overview
  
  [www.openholidaysapi.org](https://www.openholidaysapi.org/en/api/) 2026-03-28
- OpenHolidays API — GitHub Repository
  
  [github.com](https://github.com/openpotato/openholidaysapi) 2026-03-28

## Related Documentation

- [Packet Parser Integration](https://taphome.com/en/compatibility/packet-parser-guide/)
- [Packet Parser (HTTP, TCP, UDP, FTP, MQTT)](https://taphome.com/en/docs/integration/packet-parser/)
- [Packet parser functions](https://taphome.com/en/docs/script/packet-parser/)
- [Parsing functions](https://taphome.com/en/docs/script/parsing-functions/)