TapHome

OpenHolidays API

Packet Parser → HTTP
Přidal
Poslední aktualizace: 03. 2026

OpenHolidays API je bezplatné open-source REST API, které poskytuje údaje o státních svátcích a školních prázdninách pro více než 35 zemí. TapHome se připojuje k této cloudové službě přes HTTPS pomocí PacketParser HTTP šablony — není potřeba žádná autentizace ani API klíč.

Šablona poskytuje tři zařízení s booleovským stavem (pouze čtení): jedno pro státní svátky, jedno pro školní prázdniny a jedno pro víkendy. Tato zařízení lze využít ve smart rules k přizpůsobení harmonogramu vytápění, režimů alarmu, světelných scén nebo jakékoli jiné automatizace podle toho, zda je dnes pracovní den nebo ne.

Šablonu vytvořil ToBo, komunitní přispěvatel.

Konfigurace

Při importu šablony jsou vyžadovány dva parametry:

  • Country — ISO 3166-1 alpha-2 kód země (např. SK pro Slovensko, DE pro Německo, CZ pro Česko). Kompletní seznam podporovaných zemí je dostupný na https://openholidaysapi.org/Countries.
  • Region — ISO 3166-2 kód subdivize (např. SK-BC pro Banskobystrický kraj, DE-BY pro Bavorsko). Seznam subdivizí pro danou zemi je dostupný na https://openholidaysapi.org/Subdivisions?countryIsoCode={CountryCode}.

Oba parametry jsou uloženy jako Module Variables v TapHome a lze je změnit po importu bez nutnosti opětovného importu šablony.

Mnohé země mají regionálně specifické svátky. Pokud detekce svátků vypadá nesprávně, ověřte, že kód subdivize odpovídá správnému regionu — nejen kódu země.

Schopnosti zařízení

Detekce státních svátků

Zařízení Státní svátek dotazuje endpoint GET /PublicHolidays jednou za hodinu. Odešle dnešní datum spolu s nakonfigurovanými kódy země a regionu. Pokud API vrátí záznam o svátku pro dané datum, zařízení zobrazí Yes; jinak zobrazí No.

Detekce školních prázdnin

Zařízení Školní prázdniny funguje stejně, ale dotazuje endpoint GET /SchoolHolidays. Detekuje, zda dnešní den spadá do období školních prázdnin pro nakonfigurovanou zemi a region.

Dostupnost údajů o školních prázdninách se liší podle země. Některé země mají omezené pokrytí subdivizí — zkontrolujte dokumentaci API a ověřte, že váš region je podporovaný.

Detekce víkendů

Zařízení Víkend nevolá API. Používá lokální funkci TapHome NOW().DAYOFWEEK k určení, zda je dnes sobota (den 6) nebo neděle (den 0). Toto zařízení funguje nezávisle na API a nepotřebuje internetové připojení.

Další schopnosti

OpenHolidays API rovněž poskytuje endpointy pro dotazování svátků podle konkrétního data napříč všemi zeměmi (/PublicHolidaysByDate, /SchoolHolidaysByDate), výpis podporovaných zemí a regionálních subdivizí a získávání statistik o dostupných datových rozsazích. Tyto mohou být doplněny v budoucí aktualizaci šablony.

Řešení problémů

Detekce svátků vrací nesprávné výsledky
  1. Ověřte, že kód země je správný — ke kontrole seznamu podporovaných zemí použijte endpoint /Countries
  2. Ověřte kód regionu (subdivize) — některé státní svátky jsou regionálně specifické a nezobrazí se s nesprávným kódem subdivize
  3. Zkontrolujte API přímo v prohlížeči: https://openholidaysapi.org/PublicHolidays?countryIsoCode=SK&subdivisionCode=SK-BC&validFrom=2026-01-01&validTo=2026-01-01 — nahraďte datum a kódy vašimi hodnotami
  4. Pokud API vrátí prázdné pole [] pro datum, které by mělo být svátkem, údaje pro danou zemi nebo rok ještě nemusí být dostupné
Zařízení zobrazuje chybu (NaN)

Pokud je API nedostupné (problém se sítí, selhání DNS nebo výpadek API), šablona vrátí NaN s HTTP stavovým kódem v chybové zprávě. OpenHolidays API je komunitní projekt bez SLA — aktuální dostupnost zkontrolujte na stránce stavu na https://openpotato.github.io/uptime/.

OpenHolidays API je komunitně udržovaný open data projekt. Přestože je spolehlivě dostupný, neexistuje žádná garance dostupnosti. Pro kritické automatizace zvažte přidání záložního pravidla, které elegantně zpracuje chybový stav.

Dostupná zařízení

OpenHolidays Modul
Vlastní proměnné
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}
Státní svátek Přepínač Pouze ke čtení

Dotazuje OpenHolidays API jednou za hodinu — Ano, pokud je dnes státní svátek pro nakonfigurovanou zemi a region, jinak Ne

boolean json_path
Hodnoty / Stavy: Yes · No

Státní svátek

Čtení stavu přepínače
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
Školní prázdniny Přepínač Pouze ke čtení

Dotazuje OpenHolidays API jednou za hodinu — Ano, pokud dnes spadá do období školních prázdnin pro nakonfigurovanou zemi a region, jinak Ne

boolean json_path
Hodnoty / Stavy: Yes · No

Školní prázdniny

Čtení stavu přepínače
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
Víkend Přepínač Pouze ke čtení

Lokální výpočet — Ano v sobotu a neděli, Ne v pracovní dny. Nepoužívá API.

boolean
Hodnoty / Stavy: Yes · No

Víkend

Čtení stavu přepínače
var dt := NOW();
return(dt.DAYOFWEEK = 0 or dt.DAYOFWEEK = 6);
Připojení: Packet Parser → HTTP
Možná vylepšení (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

Zdroje