TapHome

OpenHolidays API

Packet Parser → HTTP
Inviato da
Ultimo aggiornamento: 03. 2026

L’OpenHolidays API è un’API REST gratuita e open-source che fornisce dati sulle festività e sulle vacanze scolastiche per oltre 35 paesi. TapHome si connette a questo servizio cloud tramite HTTPS utilizzando un template PacketParser HTTP — non è necessaria alcuna autenticazione né chiave API.

Il template fornisce tre dispositivi booleani in sola lettura: uno per le festività, uno per le vacanze scolastiche e uno per i fine settimana. Questi possono essere utilizzati nelle smart rules di TapHome per regolare programmi di riscaldamento, modalità di allarme, scene di illuminazione o qualsiasi altra automazione in base al fatto che oggi sia un giorno lavorativo o meno.

Il template è stato creato da ToBo, un contributore della comunità.

Configurazione

Durante l’importazione del template sono richiesti due parametri:

  • Country — codice paese ISO 3166-1 alpha-2 (es. SK per la Slovacchia, DE per la Germania, CZ per la Repubblica Ceca). L’elenco completo dei paesi supportati è disponibile su https://openholidaysapi.org/Countries.
  • Region — codice di suddivisione ISO 3166-2 (es. SK-BC per la regione di Banská Bystrica, DE-BY per la Baviera). L’elenco delle suddivisioni per un dato paese è disponibile su https://openholidaysapi.org/Subdivisions?countryIsoCode={CountryCode}.

Entrambi i parametri sono memorizzati come Module Variables in TapHome e possono essere modificati dopo l’importazione senza reimportare il template.

Molti paesi hanno festività specifiche per regione. Se il rilevamento delle festività sembra errato, verifica che il codice di suddivisione corrisponda alla regione corretta — non solo al codice del paese.

Funzionalità dei dispositivi

Rilevamento festività

Il dispositivo Giorno festivo interroga l’endpoint GET /PublicHolidays una volta all’ora. Invia la data odierna insieme ai codici paese e regione configurati. Se l’API restituisce una voce festiva per quella data, il dispositivo mostra Yes; altrimenti mostra No.

Rilevamento vacanze scolastiche

Il dispositivo Vacanza scolastica funziona allo stesso modo ma interroga l’endpoint GET /SchoolHolidays. Rileva se oggi ricade in un periodo di vacanza scolastica per il paese e la regione configurati.

La disponibilità dei dati sulle vacanze scolastiche varia in base al paese. Alcuni paesi hanno una copertura limitata delle suddivisioni — consulta la documentazione API per verificare che la tua regione sia supportata.

Rilevamento fine settimana

Il dispositivo Fine settimana non chiama l’API. Utilizza la funzione locale di TapHome NOW().DAYOFWEEK per determinare se oggi è sabato (giorno 6) o domenica (giorno 0). Questo dispositivo funziona indipendentemente dall’API e non richiede una connessione internet.

Funzionalità aggiuntive

L’OpenHolidays API espone anche endpoint per interrogare le festività in base a una data specifica in tutti i paesi (/PublicHolidaysByDate, /SchoolHolidaysByDate), elencare i paesi supportati e le suddivisioni regionali e ottenere statistiche sugli intervalli di dati disponibili. Questi possono essere aggiunti in un futuro aggiornamento del template.

Risoluzione dei problemi

Il rilevamento delle festività restituisce risultati errati
  1. Verifica che il codice paese sia corretto — usa l’endpoint /Countries per controllare l’elenco dei paesi supportati
  2. Verifica il codice della regione (suddivisione) — alcune festività sono specifiche per regione e non appariranno con un codice di suddivisione errato
  3. Controlla l’API direttamente nel browser: https://openholidaysapi.org/PublicHolidays?countryIsoCode=SK&subdivisionCode=SK-BC&validFrom=2026-01-01&validTo=2026-01-01 — sostituisci la data e i codici con i tuoi valori
  4. Se l’API restituisce un array vuoto [] per una data che dovrebbe essere festiva, i dati per quel paese o anno potrebbero non essere ancora disponibili
Il dispositivo mostra un errore (NaN)

Se l’API non è raggiungibile (problema di rete, errore DNS o interruzione dell’API), il template restituisce NaN con il codice di stato HTTP nel messaggio di errore. L’OpenHolidays API è un progetto comunitario senza SLA — controlla la disponibilità attuale sulla pagina di stato su https://openpotato.github.io/uptime/.

L’OpenHolidays API è un progetto open data mantenuto dalla comunità. Sebbene sia stato disponibile in modo affidabile, non esiste alcuna garanzia di uptime. Per automazioni mission-critical, considera l’aggiunta di una regola di fallback che gestisca lo stato di errore in modo elegante.

Dispositivi disponibili

OpenHolidays Modulo
Variabili personalizzate
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}
Giorno festivo Interruttore Solo lettura

Interroga l'API OpenHolidays una volta all'ora — Sì se oggi è un giorno festivo per il paese e la regione configurati, altrimenti No

boolean json_path
Valori / Stati: Yes · No

Giorno festivo

Lettura stato interruttore
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
Vacanza scolastica Interruttore Solo lettura

Interroga l'API OpenHolidays una volta all'ora — Sì se oggi ricade in un periodo di vacanza scolastica per il paese e la regione configurati, altrimenti No

boolean json_path
Valori / Stati: Yes · No

Vacanza scolastica

Lettura stato interruttore
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
Fine settimana Interruttore Solo lettura

Calcolo locale — Sì il sabato e la domenica, No nei giorni feriali. Non utilizza l'API.

boolean
Valori / Stati: Yes · No

Fine settimana

Lettura stato interruttore
var dt := NOW();
return(dt.DAYOFWEEK = 0 or dt.DAYOFWEEK = 6);
Connessione: Packet Parser → HTTP
Possibili miglioramenti (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

Fonti