TapHome

OpenHolidays API

Packet Parser → HTTP
Dodane przez
Ostatnia aktualizacja: 03. 2026

OpenHolidays API to bezpłatne, otwarte REST API dostarczające dane o świętach państwowych i feriach szkolnych dla ponad 35 krajów. TapHome łączy się z tą usługą chmurową przez HTTPS za pomocą szablonu PacketParser HTTP — nie jest wymagane uwierzytelnianie ani klucz API.

Szablon udostępnia trzy urządzenia logiczne tylko do odczytu: jedno dla świąt państwowych, jedno dla ferii szkolnych i jedno dla weekendów. Mogą one być wykorzystywane w smart rules TapHome do dostosowania harmonogramów ogrzewania, trybów alarmu, scen oświetleniowych lub dowolnej innej automatyzacji w zależności od tego, czy dziś jest dzień roboczy.

Szablon został stworzony przez ToBo, członka społeczności.

Konfiguracja

Podczas importu szablonu wymagane są dwa parametry:

  • Country — kod kraju ISO 3166-1 alpha-2 (np. SK dla Słowacji, DE dla Niemiec, CZ dla Czech). Pełna lista obsługiwanych krajów jest dostępna pod adresem https://openholidaysapi.org/Countries.
  • Region — kod jednostki podziału ISO 3166-2 (np. SK-BC dla regionu Banská Bystrica, DE-BY dla Bawarii). Lista jednostek podziału dla danego kraju jest dostępna pod adresem https://openholidaysapi.org/Subdivisions?countryIsoCode={CountryCode}.

Oba parametry są przechowywane jako Module Variables w TapHome i mogą być zmieniane po imporcie bez ponownego importowania szablonu.

Wiele krajów ma regionalne święta. Jeśli wykrywanie świąt wydaje się nieprawidłowe, sprawdź, czy kod jednostki podziału odpowiada właściwemu regionowi — nie tylko kodowi kraju.

Możliwości urządzeń

Wykrywanie świąt

Urządzenie Święto odpytuje endpoint GET /PublicHolidays raz na godzinę. Wysyła dzisiejszą datę wraz ze skonfigurowanymi kodami kraju i regionu. Jeśli API zwróci wpis świąteczny dla tej daty, urządzenie pokazuje Yes; w przeciwnym razie pokazuje No.

Wykrywanie ferii szkolnych

Urządzenie Ferie szkolne działa tak samo, ale odpytuje endpoint GET /SchoolHolidays. Wykrywa, czy dzisiejszy dzień przypada na okres ferii szkolnych dla skonfigurowanego kraju i regionu.

Dostępność danych o feriach szkolnych różni się w zależności od kraju. Niektóre kraje mają ograniczone pokrycie jednostek podziału — sprawdź dokumentację API, aby potwierdzić, że Twój region jest obsługiwany.

Wykrywanie weekendów

Urządzenie Weekend nie wywołuje API. Wykorzystuje lokalną funkcję TapHome NOW().DAYOFWEEK do określenia, czy dziś jest sobota (dzień 6) czy niedziela (dzień 0). To urządzenie działa niezależnie od API i nie wymaga połączenia z internetem.

Dodatkowe możliwości

OpenHolidays API udostępnia również endpointy do odpytywania świąt według konkretnej daty we wszystkich krajach (/PublicHolidaysByDate, /SchoolHolidaysByDate), listowania obsługiwanych krajów i regionalnych jednostek podziału oraz pobierania statystyk o dostępnych zakresach danych. Mogą one zostać dodane w przyszłej aktualizacji szablonu.

Rozwiązywanie problemów

Wykrywanie świąt zwraca nieprawidłowe wyniki
  1. Sprawdź, czy kod kraju jest prawidłowy — użyj endpointu /Countries, aby sprawdzić listę obsługiwanych krajów
  2. Sprawdź kod regionu (jednostki podziału) — niektóre święta są regionalne i nie pojawią się z nieprawidłowym kodem jednostki podziału
  3. Sprawdź API bezpośrednio w przeglądarce: https://openholidaysapi.org/PublicHolidays?countryIsoCode=SK&subdivisionCode=SK-BC&validFrom=2026-01-01&validTo=2026-01-01 — zastąp datę i kody swoimi wartościami
  4. Jeśli API zwraca pustą tablicę [] dla daty, która powinna być świętem, dane dla tego kraju lub roku mogą nie być jeszcze dostępne
Urządzenie pokazuje błąd (NaN)

Jeśli API jest nieosiągalne (problem z siecią, błąd DNS lub przerwa w działaniu API), szablon zwraca NaN z kodem statusu HTTP w komunikacie o błędzie. OpenHolidays API to projekt społecznościowy bez SLA — aktualną dostępność sprawdź na stronie statusu pod adresem https://openpotato.github.io/uptime/.

OpenHolidays API to społecznościowy projekt open data. Choć jest niezawodnie dostępny, nie ma gwarancji czasu działania. W przypadku krytycznych automatyzacji rozważ dodanie reguły zapasowej, która elegancko obsłuży stan błędu.

Dostępne urządzenia

OpenHolidays Moduł
Zmienne niestandardowe
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}
Święto Przełącznik Tylko do odczytu

Odpytuje OpenHolidays API raz na godzinę — Tak, jeśli dziś jest święto dla skonfigurowanego kraju i regionu, w przeciwnym razie Nie

boolean json_path
Wartości / Stany: Yes · No

Święto

Odczyt stanu przełącznika
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
Ferie szkolne Przełącznik Tylko do odczytu

Odpytuje OpenHolidays API raz na godzinę — Tak, jeśli dziś wypada w okresie ferii szkolnych dla skonfigurowanego kraju i regionu, w przeciwnym razie Nie

boolean json_path
Wartości / Stany: Yes · No

Ferie szkolne

Odczyt stanu przełącznika
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 Przełącznik Tylko do odczytu

Obliczenie lokalne — Tak w sobotę i niedzielę, Nie w dni robocze. Nie korzysta z API.

boolean
Wartości / Stany: Yes · No

Weekend

Odczyt stanu przełącznika
var dt := NOW();
return(dt.DAYOFWEEK = 0 or dt.DAYOFWEEK = 6);
Połączenie: Packet Parser → HTTP
Możliwe ulepszenia (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

Źródła