--- title: "OpenWeather" description: "Integrazione API OpenWeather per TapHome — meteo attuale, previsioni a 3 ore e 24 ore con temperatura, umidità, pressione, visibilità, velocità del vento." url: "https://taphome.com/it/compatibility/openweather/" language: it lastmod: 2026-03-28 generator: hugo ai: topics: ["http","data-service","cloud-api","weather","packet-parser"] questions: ["Come integrare OpenWeather con TapHome?","Cosa offre il template OpenWeather per TapHome?","Come ottenere una chiave API OpenWeather gratuita per TapHome?","Quali dati meteo legge TapHome da OpenWeather?","Come funziona il selettore multi-valore delle condizioni meteo in TapHome?","L'API OpenWeather è gratuita per l'uso con TapHome?"] --- # OpenWeather Comunicazione: Packet Parser → HTTP - [Sito ufficiale OpenWeather](https://openweathermap.org/) ## Guida all'integrazione OpenWeather è un fornitore di dati meteorologici che offre informazioni meteo globali tramite REST API. Il template TapHome si connette all'API gratuita OpenWeather v2.5 tramite HTTPS e legge le condizioni meteorologiche attuali, una previsione a 3 ore e una previsione a 24 ore per una posizione configurata. Il template effettua due chiamate API ogni 5 minuti — una per il meteo attuale e una per la previsione a 5 giorni/3 ore. Fornisce 18 dispositivi in sola lettura che coprono temperatura dell'aria, temperatura percepita, umidità, pressione atmosferica, visibilità, velocità del vento e condizioni meteorologiche. Tutte le temperature sono in Celsius (unità metriche) e non è richiesto alcun abbonamento a pagamento. ## Configurazione ### Ottenere la chiave API 1. Registra un account gratuito su [openweathermap.org](https://home.openweathermap.org/users/sign_up) — non è richiesta carta di credito 2. Dopo la registrazione, la chiave API (APPID) viene inviata tramite e-mail di conferma 3. La chiave è disponibile anche nella pagina account sotto la scheda **API key** 4. Le nuove chiavi si attivano automaticamente, in genere da 10 minuti a 2 ore > [!TIP] > Il piano gratuito consente 60 chiamate al minuto e 1.000.000 di chiamate al mese. Il template TapHome effettua circa 576 chiamate al giorno (2 chiamate ogni 5 minuti), rientrando ampiamente nei limiti gratuiti. ### Parametri di importazione Durante l'importazione del template in TapHome, sono richiesti tre parametri: | Parametro | Descrizione | Esempio | |-----------|-------------|---------| | `latitude` | Latitudine della posizione in gradi decimali | `48.1778` | | `longitude` | Longitudine della posizione in gradi decimali | `17.1426` | | `appid` | Chiave API OpenWeather dal dashboard dell'account | `a1b2c3d4e5f6...` | Per trovare le coordinate di una posizione, fai clic con il tasto destro su [Google Maps](https://maps.google.com) e seleziona le coordinate dal menu contestuale. ### Endpoint API Il modulo si connette ad `api.openweathermap.org` tramite HTTPS (porta 443) e chiama due endpoint per ciclo di polling: ``` GET /data/2.5/weather?units=metric&lat={latitude}&lon={longitude}&appid={AppId} GET /data/2.5/forecast?units=metric&lat={latitude}&lon={longitude}&appid={AppId}&cnt=9 ``` La prima richiesta restituisce le condizioni meteorologiche attuali. La seconda restituisce un elenco di previsioni dove `list[0]` è il prossimo slot a 3 ore e `list[8]` è lo slot a +24 ore (8 x 3h = 24h). ## Funzionalità dei dispositivi Il template espone 18 dispositivi in sola lettura organizzati in tre gruppi: meteo attuale (6 dispositivi), previsione a 3 ore (6 dispositivi) e previsione a 24 ore (6 dispositivi). Ogni gruppo fornisce le stesse sei misurazioni. ### Temperatura e umidità - **Current Air Temperature** — temperatura attuale in Celsius con umidità come valore secondario (l'API restituisce 0–100%, convertito nel rapporto 0–1 per TapHome) - **Current Feels Like Temperature** — temperatura percepita che tiene conto del wind chill e dell'umidità. La funzionalità umidità è disabilitata (restituisce NaN) — viene utilizzato solo il valore della temperatura - **Forecast (+3h) Air Temperature** — temperatura e umidità per il prossimo slot di previsione a 3 ore. Include un attributo di servizio **Forecast Date** che mostra il timestamp del punto dati - **Forecast (+3h) Feels Like Temperature** — temperatura percepita per il prossimo slot a 3 ore - **Forecast (+24h) Air Temperature** — temperatura e umidità per lo slot di previsione a +24h. Include un attributo di servizio **Forecast Date** - **Forecast (+24h) Feels Like Temperature** — temperatura percepita per lo slot a +24h ### Pressione atmosferica e visibilità - **Current Air Pressure** — pressione atmosferica in hPa - **Current Visibility** — distanza di visibilità in metri (massimo 10.000 m) - **Forecast (+3h) Air Pressure** — pressione atmosferica per il prossimo slot a 3 ore - **Forecast (+3h) Visibility** — visibilità per la previsione a 3 ore - **Forecast (+24h) Air Pressure** — pressione atmosferica per lo slot a +24h - **Forecast (+24h) Visibility** — visibilità per la previsione a 24 ore > [!WARNING] > I dispositivi Forecast (+3h) Visibility e Forecast (+24h) Visibility hanno gli indici dei dati invertiti nella versione attuale del template. Il dispositivo +3h legge da list[8] (la posizione 24h) e il dispositivo +24h legge da list[0] (la posizione 3h). I valori sono invertiti fino alla correzione in un futuro aggiornamento del template. ### Velocità del vento - **Current Wind Speed** — velocità del vento in m/s - **Forecast (+3h) Wind Speed** — velocità del vento per il prossimo slot a 3 ore - **Forecast (+24h) Wind Speed** — velocità del vento per lo slot a +24h ### Condizioni meteorologiche Tre dispositivi selettore multi-valore visualizzano la categoria delle condizioni meteorologiche: - **Current Weather** — condizione meteorologica attuale - **Forecast (+3h) Weather** — condizione meteorologica per il prossimo slot a 3 ore - **Forecast (+24h) Weather** — condizione meteorologica per lo slot a +24h Ogni dispositivo meteo mappa il campo API `weather[0].main` su una delle 7 categorie: | Valore selettore | Etichetta | Gruppi meteo API | |------------------|-----------|------------------| | 0 | Clear | Clear | | 1 | Clouds | Clouds | | 2 | Rain | Rain | | 3 | Drizzle | Drizzle | | 4 | Thunderstorm | Thunderstorm | | 5 | Snow | Snow | | 6 | Atmosphere | Mist, Smoke, Haze, Dust, Fog, Sand, Ash, Squall, Tornado | Se l'API restituisce un gruppo meteo non riconosciuto, il selettore assume il valore predefinito 0 (Clear). I valori 7, 8 e 9 del selettore sono definiti nella configurazione del template ma non hanno mappatura nella logica dello script — sono segnaposto non utilizzati. ### Funzionalità aggiuntive L'API OpenWeather fornisce anche direzione del vento, raffiche di vento, percentuale di nuvolosità, volume di pioggia e neve (1h) e orari di alba/tramonto. L'umidità è esposta solo come valore secondario sui sensori di temperatura, non come dispositivo autonomo. Queste funzionalità possono essere aggiunte in un futuro aggiornamento del template. ## Risoluzione dei problemi ### Tutti i dispositivi mostrano NaN o nessun dato 1. Verifica che il TapHome Core abbia accesso a internet — il template richiede connettività HTTPS in uscita verso `api.openweathermap.org` 2. Controlla che la chiave API sia valida — apri `https://api.openweathermap.org/data/2.5/weather?lat=48.18&lon=17.14&appid=YOUR_KEY&units=metric` nel browser per verificare 3. Le nuove chiavi API possono richiedere fino a 2 ore per l'attivazione dopo la registrazione 4. Conferma che i valori di latitudine e longitudine siano coordinate decimali corrette (non gradi/minuti/secondi) ### I dati di previsione sembrano errati L'API di previsione restituisce dati a intervalli di 3 ore. I dispositivi +3h leggono il primo slot di previsione (`list[0]`), che è il prossimo blocco a 3 ore disponibile — non esattamente 3 ore da adesso. Analogamente, i dispositivi +24h leggono `list[8]` (il 9° slot), che rappresenta circa 24 ore avanti. Nota l'inversione degli indici di visibilità descritta nell'avviso sopra — se i valori di visibilità +3h e +24h sembrano invertiti, si tratta del bug noto del template. ### Errore di battitura nel nome del dispositivo Il dispositivo n. 17 nel template si chiama "Forecast (+24h)Weather" (manca lo spazio prima di "Weather"). Si tratta di un problema estetico nel XML del template che non influisce sulla funzionalità. Il dispositivo viene visualizzato correttamente nella tabella dispositivi TapHome utilizzando il suo nome arricchito. ## Dispositivi disponibili 18 Questi dispositivi compaiono in TapHome dopo l'importazione. OpenWeather Modulo Variabili personalizzate | | | |----------------------|--------------------------------------------------------------------------------------------------------------------------| | `longitude` (string) | Longitudine geografica della posizione della stazione meteorologica in gradi decimali (impostata durante l'importazione) | | `latitude` (string) | Latitudine geografica della posizione della stazione meteorologica in gradi decimali (impostata durante l'importazione) | | `AppId` (string) | Chiave API OpenWeather (ottieni chiave gratuita su openweathermap.org/api) | Lettura (modulo) ```taphome responseJson := "error"; Daily := "error"; VAR path := "data/2.5/weather?units=metric&lat=" + latitude + "&lon=" + longitude + "&appid=" + AppId; VAR response := SENDHTTPREQUEST(path); IF response.IsSuccess responseJson := response.Content; ELSE VAR contentJson := response.Content; VAR errCode := response.StatusCode; VAR message := PARSEJSON(contentJson, "message"); #ADDERROR("Failed to read data - (" + errCode + ") " + message); END path := "data/2.5/forecast?units=metric&lat=" + latitude + "&lon=" + longitude + "&appid=" + AppId + "&cnt=9"; response := SENDHTTPREQUEST(path); IF response.IsSuccess Daily := response.Content; ELSE contentJson := response.Content; errCode := response.StatusCode; message := PARSEJSON(contentJson, "message"); #ADDERROR("Failed to read data - (" + errCode + ") " + message); END ``` Pressione atmosferica attuale Variabile Solo lettura numeric Unità: hPa json\_path Lettura ```taphome IF(ISNULL(responseJson) | responseJson = "error", NaN, PARSEJSON(responseJson,"main.pressure")) ``` Lettura (modulo) ```taphome IF(ISNULL(responseJson) | responseJson = "error", ADDERROR("Failed to read data ")); ``` Temperatura dell'aria attuale Sensore di temperatura Solo lettura Temperatura e umidità attuali — l'umidità è divisa per 100 (l'API restituisce 0–100%, TapHome si aspetta rapporto 0–1) numeric Unità: °C json\_path Lettura umidità ```taphome IF(ISNULL(responseJson) | responseJson = "error", NaN, PARSEJSON(responseJson,"main.humidity") / 100) ``` Lettura (modulo) ```taphome IF(ISNULL(responseJson) | responseJson = "error", ADDERROR("Failed to read data ")); ``` Lettura temperatura ```taphome IF(ISNULL(responseJson) | responseJson = "error", NaN, PARSEJSON(responseJson,"main.temp")) ``` Temperatura percepita attuale Sensore di temperatura Solo lettura Temperatura percepita considerando wind chill e umidità — funzione umidità disabilitata (restituisce NaN) numeric Unità: °C json\_path Lettura umidità ```taphome NaN ``` Lettura (modulo) ```taphome IF(ISNULL(responseJson) | responseJson = "error", ADDERROR("Failed to read data ")); ``` Lettura temperatura ```taphome IF(ISNULL(responseJson) | responseJson = "error", NaN, PARSEJSON(responseJson,"main.feels_like")) ``` Visibilità attuale Variabile Solo lettura Distanza di visibilità in metri (massimo 10.000 m) numeric Unità: m json\_path Lettura ```taphome IF(ISNULL(responseJson) | responseJson = "error", NaN, PARSEJSON(responseJson,"visibility")) ``` Lettura (modulo) ```taphome IF(ISNULL(responseJson) | responseJson = "error", ADDERROR("Failed to read data ")); ``` Meteo attuale Interruttore multivalore Solo lettura Condizione meteo come interruttore multivalore — sereno, nuvoloso, pioggia, pioggerella, temporale, neve, atmosfera string multi\_value\_switch Valori / Stati: Clear · Clouds · Rain · Drizzle · Thunderstorm · Snow · Atmosphere Lettura stato interruttore ```taphome IF(ISNULL(responseJson) | responseJson = "error") return(NaN); END VAR weather := PARSEJSON(responseJson, "weather[0].main"); SWITCH(weather, "Clear", 0, "Clouds", 1, "Rain", 2, "Drizzle", 3, "Thunderstorm", 4, "Snow", 5, "Mist", 6, "Smoke", 6, "Haze", 6, "Dust", 6, "Fog", 6, "Sand", 6, "Ash", 6, "Squall", 6, "Tornado", 6, 0); ``` Lettura (modulo) ```taphome IF(ISNULL(responseJson) | responseJson = "error", ADDERROR("Failed to read data ")); ``` Velocità del vento attuale Variabile Solo lettura numeric Unità: m/s json\_path Lettura ```taphome IF(ISNULL(responseJson) | responseJson = "error", NaN, PARSEJSON(responseJson,"wind.speed")) ``` Lettura (modulo) ```taphome IF(ISNULL(responseJson) | responseJson = "error", ADDERROR("Failed to read data ")); ``` Previsione (+3h) Pressione atmosferica Variabile Solo lettura numeric Unità: hPa json\_path Lettura ```taphome IF(ISNULL(Daily) | Daily = "error", NaN, PARSEJSON(Daily,"$.list[0].main.pressure")) ``` Lettura (modulo) ```taphome IF(ISNULL(responseJson) | responseJson = "error", ADDERROR("Failed to read data ")); ``` Previsione (+3h) Temperatura dell'aria Sensore di temperatura Solo lettura Temperatura e umidità per il prossimo slot previsione 3 ore — include attributo di servizio Data previsione numeric Unità: °C json\_path Attributi di servizio | | | |-----------------|------------------------------------------------------------------| | Data previsione | Timestamp del punto dati previsione (dt\_txt dalla risposta API) | Lettura umidità ```taphome IF(ISNULL(Daily) | Daily = "error", NaN, PARSEJSON(Daily,"$.list[0].main.humidity") / 100) ``` Lettura (modulo) ```taphome IF(ISNULL(Daily) | Daily = "error", ADDERROR("Failed to read data ")); ``` Lettura temperatura ```taphome IF(ISNULL(Daily) | Daily = "error", NaN, PARSEJSON(Daily,"$.list[0].main.temp")) ``` Attributi di servizio Forecast Date ```taphome IF(ISNULL(Daily) | Daily = "error", NaN, PARSEJSON(Daily,"$.list[0].dt_txt")) ``` Previsione (+3h) Temperatura percepita Sensore di temperatura Solo lettura Temperatura percepita per il prossimo slot previsione 3 ore — funzione umidità disabilitata (restituisce NaN) numeric Unità: °C json\_path Lettura umidità ```taphome NaN ``` Lettura (modulo) ```taphome IF(ISNULL(responseJson) | responseJson = "error", ADDERROR("Failed to read data ")); ``` Lettura temperatura ```taphome IF(ISNULL(Daily) | Daily = "error", NaN, PARSEJSON(Daily,"$.list[0].main.feels_like")) ``` Previsione (+3h) Visibilità Variabile Solo lettura Problema noto: legge da list\[8] anziché list\[0] — valori di visibilità invertiti con Previsione (+24h) numeric Unità: m json\_path Lettura ```taphome IF(ISNULL(Daily) | Daily = "error", NaN, PARSEJSON(Daily,"$.list[8].visibility")) ``` Lettura (modulo) ```taphome IF(ISNULL(responseJson) | responseJson = "error", ADDERROR("Failed to read data ")); ``` Previsione (+3h) Meteo Interruttore multivalore Solo lettura Condizione meteo per il prossimo slot previsione 3 ore — stessa mappatura a 7 categorie del Meteo attuale string multi\_value\_switch Valori / Stati: Clear · Clouds · Rain · Drizzle · Thunderstorm · Snow · Atmosphere Lettura stato interruttore ```taphome IF(ISNULL(Daily) | Daily = "error") return(NaN); END VAR weather := PARSEJSON(Daily, "$.list[0].weather[0].main"); SWITCH(weather, "Clear", 0, "Clouds", 1, "Rain", 2, "Drizzle", 3, "Thunderstorm", 4, "Snow", 5, "Mist", 6, "Smoke", 6, "Haze", 6, "Dust", 6, "Fog", 6, "Sand", 6, "Ash", 6, "Squall", 6, "Tornado", 6, 0); ``` Lettura (modulo) ```taphome IF(ISNULL(Daily) | Daily = "error", ADDERROR("Failed to read data ")); ``` Previsione (+3h) Velocità del vento Variabile Solo lettura numeric Unità: m/s json\_path Lettura ```taphome IF(ISNULL(Daily) | Daily = "error", NaN, PARSEJSON(Daily,"$.list[0].wind.speed")) ``` Lettura (modulo) ```taphome IF(ISNULL(responseJson) | responseJson = "error", ADDERROR("Failed to read data ")); ``` Previsione (+24h) Pressione atmosferica Variabile Solo lettura numeric Unità: hPa json\_path Lettura ```taphome IF(ISNULL(Daily) | Daily = "error", NaN, PARSEJSON(Daily,"$.list[8].main.pressure")) ``` Lettura (modulo) ```taphome IF(ISNULL(responseJson) | responseJson = "error", ADDERROR("Failed to read data ")); ``` Previsione (+24h) Temperatura dell'aria Sensore di temperatura Solo lettura Temperatura e umidità per lo slot previsione +24h — include attributo di servizio Data previsione numeric Unità: °C json\_path Attributi di servizio | | | |-----------------|------------------------------------------------------------------| | Data previsione | Timestamp del punto dati previsione (dt\_txt dalla risposta API) | Lettura umidità ```taphome IF(ISNULL(Daily) | Daily = "error", NaN, PARSEJSON(Daily,"$.list[8].main.humidity") / 100) ``` Lettura (modulo) ```taphome IF(ISNULL(Daily) | Daily = "error", ADDERROR("Failed to read data ")); ``` Lettura temperatura ```taphome IF(ISNULL(Daily) | Daily = "error", NaN, PARSEJSON(Daily,"$.list[8].main.temp")) ``` Attributi di servizio Forecast Date ```taphome IF(ISNULL(Daily) | Daily = "error", NaN, PARSEJSON(Daily,"$.list[8].dt_txt")) ``` Previsione (+24h) Temperatura percepita Sensore di temperatura Solo lettura Temperatura percepita per lo slot previsione +24h — funzione umidità disabilitata (restituisce NaN) numeric Unità: °C json\_path Lettura umidità ```taphome NaN ``` Lettura (modulo) ```taphome IF(ISNULL(responseJson) | responseJson = "error", ADDERROR("Failed to read data ")); ``` Lettura temperatura ```taphome IF(ISNULL(Daily) | Daily = "error", NaN, PARSEJSON(Daily,"$.list[8].main.feels_like")) ``` Previsione (+24h) Visibilità Variabile Solo lettura Problema noto: legge da list\[0] anziché list\[8] — valori di visibilità invertiti con Previsione (+3h) numeric Unità: m json\_path Lettura ```taphome IF(ISNULL(Daily) | Daily = "error", NaN, PARSEJSON(Daily,"$.list[0].visibility")) ``` Lettura (modulo) ```taphome IF(ISNULL(responseJson) | responseJson = "error", ADDERROR("Failed to read data ")); ``` Previsione (+24h) Velocità del vento Variabile Solo lettura numeric Unità: m/s json\_path Lettura ```taphome IF(ISNULL(Daily) | Daily = "error", NaN, PARSEJSON(Daily,"$.list[8].wind.speed")) ``` Previsione (+24h) Meteo Interruttore multivalore Solo lettura Condizione meteo per lo slot previsione +24h — stessa mappatura a 7 categorie del Meteo attuale string multi\_value\_switch Valori / Stati: Clear · Clouds · Rain · Drizzle · Thunderstorm · Snow · Atmosphere Lettura stato interruttore ```taphome IF(ISNULL(Daily) | Daily = "error") return(NaN); END VAR weather := PARSEJSON(Daily, "$.list[8].weather[0].main"); SWITCH(weather, "Clear", 0, "Clouds", 1, "Rain", 2, "Drizzle", 3, "Thunderstorm", 4, "Snow", 5, "Mist", 6, "Smoke", 6, "Haze", 6, "Dust", 6, "Fog", 6, "Sand", 6, "Ash", 6, "Squall", 6, "Tornado", 6, 0); ``` **Connessione:** Packet Parser → HTTP Possibili miglioramenti (7) - Current Humidity (standalone) — Humidity is only exposed as secondary value on temperature sensors, not as standalone device - Wind Direction — Wind direction in degrees available in API but not implemented in template - Wind Gust — Wind gust speed available in API but not implemented in template - Cloudiness — Cloudiness percentage available in API but not implemented - Rain Volume (1h) — Rain volume for last 1 hour in mm, available in API - Snow Volume (1h) — Snow volume for last 1 hour in mm, available in API - Sunrise / Sunset — Unix timestamps for sunrise and sunset available in API ## Parametri di importazione Inserisci questi valori quando importi l'XML. | Richiesto nell'app | Predefinito | |----------------------------|-------------| | latitude | `48.1778` | | longitude | `17.1426` | | OpenWeather application id | `appid` | ## Fonti - Current Weather Data API 2.5 [openweathermap.org](https://openweathermap.org/current) 2026-03-28 - 5 Day / 3 Hour Forecast API [openweathermap.org](https://openweathermap.org/forecast5) 2026-03-28 - Weather Condition Codes [openweathermap.org](https://openweathermap.org/weather-conditions) 2026-03-28 - API Key Setup Guide [openweathermap.org](https://openweathermap.org/appid) 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/)