---
title: "OpenHolidays API"
description: "Integrazione OpenHolidays API per TapHome. Interroga festività e vacanze scolastiche per oltre 35 paesi via HTTP — automatizza riscaldamento,."
url: "https://taphome.com/it/compatibility/openholidays/"
language: it
lastmod: 2026-03-28
generator: hugo
ai:
  topics: ["http","other","rest-api","holiday-detection","scheduling"]
  questions: ["Come integrare l'API OpenHolidays con TapHome?","Come rileva TapHome automaticamente le festività?","Come configurare i codici paese e regione per OpenHolidays in TapHome?","Perché il dispositivo festività mostra risultati errati?","Qual è la differenza tra IsPublicHoliday e IsSchoolHoliday in TapHome?","TapHome può adattare i programmi di riscaldamento in base alle festività?"]
---

# OpenHolidays API

Comunicazione: Packet Parser → HTTP

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

## Guida all'integrazione

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.

> [!TIP]
> 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.

> [!NOTE]
> 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/`.

> [!WARNING]
> 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 3

Questi dispositivi compaiono in TapHome dopo l'importazione.

OpenHolidays Modulo

Variabili personalizzate

`Country` (string) Codice paese ISO 3166-1 alpha-2 (es. SK, DE, CZ)

Full list at openholidaysapi.org/Countries

`Region` (string) Codice suddivisione ISO 3166-2 (es. 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

Lettura stato interruttore

```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
```

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

Lettura stato interruttore

```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
```

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

Lettura stato interruttore

```taphome
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

## Parametri di importazione

Inserisci questi valori quando importi l'XML.

| Richiesto nell'app | Predefinito |
|--------------------|-------------|
| Country            | `SK`        |
| Region             | `SK-BC`     |

## Fonti

- 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

## Documentazione correlata

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