TapHome

Forecast.Solar

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

Forecast.Solar è un’API cloud gratuita che fornisce stime di produzione energetica solare FV basate sulla posizione, l’orientamento dei pannelli e la capacità installata. Combina i dati di irraggiamento del EU Photovoltaic Geographical Information System (PVGIS) con le previsioni meteo per prevedere quanta energia produrrà un impianto solare.

TapHome si connette a questo servizio tramite HTTPS utilizzando un template PacketParser HTTP. Il template interroga l’endpoint /estimate una volta all’ora (entro il limite del piano gratuito di 12 richieste all’ora) e fornisce sei sensori energetici in sola lettura: quattro finestre temporali della giornata corrente e totali giornalieri per oggi e domani. Non è richiesta autenticazione né chiave API.

Configurazione

Durante l’importazione del template sono richiesti cinque parametri. Questi definiscono l’impianto solare e vengono utilizzati per costruire l’URL della richiesta API:

  • Latitude — latitudine decimale della posizione del sistema FV (es. 48.1778 per Bratislava). Intervallo: da -90 a 90, precisione fino a 0,0001 (~10 m).
  • Longitude — longitudine decimale della posizione del sistema FV (es. 17.1426 per Bratislava). Intervallo: da -180 a 180.
  • PV_declination — angolo di inclinazione dei pannelli in gradi. 0 = orizzontale (tetto piano), 90 = verticale (montaggio a parete). Valori residenziali tipici: 20–45.
  • PV_azimuth — orientamento dei pannelli rispetto ai punti cardinali. -180 o 180 = nord, -90 = est, 0 = sud, 90 = ovest. Per pannelli orientati a sud usare 0.
  • PV_kWp — potenza FV totale installata in kilowatt di picco (es. 5 per un sistema da 5 kWp).

Tutti e cinque i parametri sono memorizzati come Variabili del Modulo in TapHome e possono essere modificati dopo l’importazione senza reimportare il template.

L’API Forecast.Solar utilizza una convenzione di azimut diversa da altri strumenti. In questa API, 0 = sud e i valori aumentano in senso orario (-90 = est, 90 = ovest, 180/-180 = nord). Se provieni da Home Assistant (dove 180 = sud), sottrai 180 dal valore HA.

Per trovare le tue coordinate, fai clic destro sulla tua posizione in Google Maps e copia i valori di latitudine/longitudine.

Come funziona

Il modulo invia una singola richiesta HTTP per ciclo di polling:

1
2

GET /estimate/{Latitude}/{Longitude}/{PV_declination}/{PV_azimuth}/{PV_kWp}
Accept: application/json

L’API restituisce una risposta JSON contenente wattora cumulativi per ogni ora (watt_hours), energia per periodo (watt_hours_period), potenza istantanea (watts) e totali giornalieri (watt_hours_day). Il template analizza watt_hours e watt_hours_day per derivare tutti e sei i valori dei dispositivi.

Due attributi di servizio vengono letti dai metadati della risposta: Place (il nome della località identificata, es. “Bratislava, Slovakia”) e Time zone (es. “Europe/Bratislava”). Sono visibili nella vista dettagliata del modulo e confermano che l’API ha identificato correttamente la posizione.

Funzionalità dispositivi

Il template fornisce sei sensori energetici in sola lettura. Tutti i valori sono in wattora (Wh) e rappresentano la produzione energetica FV prevista.

Previsione energetica per finestra temporale

La giornata è divisa in quattro finestre temporali. Ogni dispositivo mostra la produzione energetica prevista per quel periodo:

  • Energy 0–9h — produzione prevista dalla mezzanotte alle 9:00. Legge il valore cumulativo di wattora al timestamp delle 09:00. Nella maggior parte delle località copre dall’alba fino al primo mattino.
  • Energy 9–12h — produzione prevista dalle 9:00 alle 12:00. Calcolata come differenza tra i valori cumulativi alle 12:00 e alle 09:00.
  • Energy 12–15h — produzione prevista dalle 12:00 alle 15:00. Calcolata come differenza tra i valori cumulativi alle 15:00 e alle 12:00. Tipicamente il periodo con la produzione più alta.
  • Energy 15–0h — produzione prevista dalle 15:00 a fine giornata. Calcolata come totale giornaliero meno il valore cumulativo alle 15:00. In pratica copre dalle 15:00 al tramonto poiché la produzione scende a zero dopo il buio.

Questa suddivisione consente alle smart rule di mirare a parti specifiche della giornata — ad esempio programmare la ricarica batterie durante il picco 12–15h o rinviare attività energivore alle ore con la produzione prevista più alta.

Totali giornalieri
  • PV Energy Forecast (Today) — produzione energetica totale prevista per la giornata corrente. Legge direttamente il valore watt_hours_day per la data odierna.
  • PV Energy Forecast (Tomorrow) — produzione energetica totale prevista per il giorno successivo. Utilizza la data di domani dalla stessa risposta API.

Questi totali sono utili per la pianificazione giornaliera — ad esempio decidere se far funzionare la pompa di calore con energia FV o dalla rete in base alla produzione solare prevista.

Funzionalità aggiuntive

L’API Forecast.Solar fornisce anche stime di potenza istantanea (watt per periodi di 15 minuti), dati energetici per periodo senza calcolo cumulativo e identificazione del tempo di picco produttivo. I piani a pagamento aggiungono supporto per orientamenti multipli dei pannelli (2–4 piani), dati storici di produzione, stime a cielo sereno e fattori di smorzamento per la regolazione dell’ombreggiatura. Questi possono essere aggiunti in un futuro aggiornamento del template.

Esempi di automazione

Ricarica batterie basata sulla previsione

Utilizza il dispositivo PV Energy Forecast (Today) in una smart rule:

  • Condizione: PV Energy Forecast (Today) > 15000 (Wh = 15 kWh)
  • Azione: impostare la batteria in modalità “ricarica solo da FV”

Nelle giornate nuvolose con previsione bassa, passa alla ricarica dalla rete durante le ore tariffarie economiche.

Pianificazione attività energivore

Utilizza i dispositivi a finestra temporale per identificare il periodo migliore per attività ad alto consumo:

  • Condizione: Energy 12–15h > 3000 (Wh)
  • Azione: avviare pompa piscina, scaldabagno o ricarica EV alle 12:00

Risoluzione problemi

Tutti i dispositivi mostrano zero o NaN
  1. Verifica la connettività Internet del TapHome Core — il template richiede accesso HTTPS in uscita verso api.forecast.solar
  2. Controlla se l’API risponde — apri https://api.forecast.solar/estimate/48.1778/17.1426/45/0/5 nel browser (sostituisci con i tuoi parametri)
  3. Se l’errore contiene un codice di stato (es. “429”), il limite di richieste è stato superato. Il piano gratuito consente 12 richieste all’ora — attendi il reset della finestra mobile
  4. Il codice di stato 400 tipicamente indica coordinate non valide (latitudine/longitudine potrebbero essere invertite o la posizione è sull’acqua)
I valori di previsione sembrano troppo alti o bassi
  1. Verifica che il parametro PV_kWp corrisponda alla capacità effettivamente installata — scala direttamente tutti i valori di previsione
  2. Controlla PV_declination — un pannello orizzontale (0) produce meno di un pannello inclinato in modo ottimale (30–40 nell’Europa centrale)
  3. Controlla PV_azimuth — verifica che l’orientamento corrisponda alla realtà. Ricorda: 0 = sud in questa API
  4. L’API utilizza dati di previsione meteo che potrebbero non riflettere le condizioni locali (edifici vicini, alberi, ombreggiatura temporanea). Usa il fattore di smorzamento tramite il piano API a pagamento per la regolazione dell’ombreggiatura
Energy 15–0h mostra valori inaspettatamente bassi

Questo è il comportamento previsto. Il dispositivo “15–0h” calcola il totale giornaliero meno la produzione cumulativa alle 15:00. Poiché la produzione FV cessa effettivamente al tramonto, questo valore rappresenta la produzione dalle 15:00 al tramonto — non fino a mezzanotte. Nei mesi invernali con tramonto anticipato, questo valore può essere molto piccolo.

L’API Forecast.Solar esegue manutenzione trimestrale il 1° di ogni mese di trimestre intorno alla mezzanotte UTC (gennaio, aprile, luglio, ottobre). Durante la manutenzione, l’API restituisce HTTP 503 e i dispositivi mostreranno temporaneamente errori.

Dispositivi disponibili

Forecast.Solar Modulo
Attributi di servizio
LuogoNome della località risolto dall'API dalle coordinate inviate — conferma che l'API ha identificato la posizione corretta
Fuso orarioFuso orario determinato dall'API per la posizione configurata — utilizzato per il corretto allineamento dei timestamp
Variabili personalizzate
Latitude (numeric)Geographic latitude of the PV installation in decimal degrees (set during import)
Longitude (numeric)Geographic longitude of the PV installation in decimal degrees (set during import)
PV_declination (numeric)Tilt angle of the PV panels in degrees (0 = horizontal, 90 = vertical)
PV_azimuth (numeric)Compass orientation of the PV panels in degrees (0 = north, 180 = south)
PV_kWp (numeric)Installed peak power of the PV system in kilowatts

forecast.solar

Lettura (modulo)
VAR response := SENDHTTPREQUEST("/estimate/" + Latitude + "/" + Longitude + "/" + PV_declination + "/" + PV_azimuth + "/" + PV_kWp, "GET", "", "Accept: application/json");
IF response.IsSuccess
    output := response.Content;
ELSE
    ADDERROR(response.StatusCode + " (" + response.ReasonPhrase + ")");
END
Attributi di servizio
Place
PARSEJSON(output, "$.message.info.place")
Time zone
PARSEJSON(output, "$.message.info.timezone")
Energia 0–9h Variabile Solo lettura

Energia FV prevista da mezzanotte alle 9:00 — wattora cumulativi al timestamp delle 09:00

numeric Unità: Wh json_path

Energia 0–9h

Lettura
var date := tostring(NOW(), "yyyy-MM-dd");

var tmp := PARSEJSON(output,"$.result.watt_hours");

PARSETEXT(tmp, date + " 09:00:00\":", ",");
Energia 9–12h Variabile Solo lettura

Energia FV prevista dalle 9:00 alle 12:00 — differenza tra wattora cumulativi alle 12:00 e alle 09:00

numeric Unità: Wh json_path

Energia 9–12h

Lettura
var date := tostring(NOW(), "yyyy-MM-dd");

var tmp := PARSEJSON(output,"$.result.watt_hours");

var h9 := PARSETEXT(tmp, date + " 09:00:00\":", ",");
var h12 := PARSETEXT(tmp, date + " 12:00:00\":", ",");

h12 - h9
Energia 12–15h Variabile Solo lettura

Energia FV prevista dalle 12:00 alle 15:00 — differenza tra wattora cumulativi alle 15:00 e alle 12:00

numeric Unità: Wh json_path

Energia 12–15h

Lettura
var date := tostring(NOW(), "yyyy-MM-dd");

var tmp := PARSEJSON(output,"$.result.watt_hours");

var h12 := PARSETEXT(tmp, date + " 12:00:00\":", ",");
var h15 := PARSETEXT(tmp, date + " 15:00:00\":", ",");

h15 - h12
Energia 15–0h Variabile Solo lettura

Energia FV prevista dalle 15:00 a fine giornata — totale giornaliero meno wattora cumulativi alle 15:00

numeric Unità: Wh json_path

Energia 15–0h

Lettura
var date := tostring(NOW(), "yyyy-MM-dd");

var tmp := PARSEJSON(output,"$.result.watt_hours");

var last := PARSEJSON(output, "$.result.watt_hours_day." + date);

var h15 := PARSETEXT(tmp, date + " 15:00:00\":", ",");

last - h15
Previsione energia FV (oggi) Variabile Solo lettura

Produzione totale prevista di energia solare per il giorno corrente in wattora

numeric Unità: Wh json_path

Previsione energia FV (oggi)

Lettura
var date := tostring(NOW(), "yyyy-MM-dd");

PARSEJSON(output, "$.result.watt_hours_day." + date)
Previsione energia FV (domani) Variabile Solo lettura

Produzione totale prevista di energia solare per il giorno successivo in wattora

numeric Unità: Wh json_path

Previsione energia FV (domani)

Lettura
var date := tostring(DATETIMEADD(NOW(), 0, 0, 1), "yyyy-MM-dd");

PARSEJSON(output, "$.result.watt_hours_day." + date)
Connessione: Packet Parser → HTTP
Possibili miglioramenti (9)
  • Instantaneous Power (watts) — Power average (W) per 15-min period — HA integration exposes this as 'Estimated Power Production — Now'
  • Energy per Period (watt_hours_period) — Energy produced in each 15-min period — alternative to cumulative watt_hours with delta calculation
  • Remaining Energy Today — Daily total minus current cumulative — HA exposes this, template could compute from existing data
  • Peak Production Time — Timestamp of highest watts value — requires iterating watts object, not trivially extractable with PARSEJSON
  • Multi-Plane Support (2-4 planes) — Paid tiers support 2-4 panel orientations per request — requires API key import parameter
  • Historic Production Data — Past production data for comparison — requires paid API key
  • Clear Sky Estimate — Theoretical maximum production without clouds — requires Professional tier API key
  • Damping Factor (shadow adjustment) — Adjusts morning/evening predictions for shadows, trees, buildings — could be added as import parameter
  • Inverter Power Limit — Limits peak prediction to inverter capacity — could be added as import parameter

Fonti