TapHome

OpenHolidays API

Packet Parser → HTTP
Submitted by
Last updated: 03. 2026

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 Banska 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.

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 Is 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 Is 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.

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 Is 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.

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

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

Public Holiday

Read switch state
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

School Holiday

Read switch state
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

Weekend

Read switch state
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

Sources