Come leggere i numeri che l'API restituisce, quanto sono freschi e ogni quanto ha senso chiederli.
Unità
| Grandezza | Unità | Tipo |
|---|---|---|
| Potenza | W | intero |
| Energia | Wh | intero, sempre ≥ 0 |
| Stato di carica | % | numero, 0–100 |
Segni
Le potenze di rete e di batteria hanno un segno:
| Campo | Positivo | Negativo |
|---|---|---|
grid_power_w |
prelievo dalla rete | immissione in rete |
battery_power_w |
batteria in carica | batteria in scarica |
Le energie invece non sono mai negative: la direzione è nel nome del campo (imported / exported, charged / discharged).
Timestamp
- I timestamp di telemetria, connettività e allarmi sono ISO 8601 in UTC (
2026-10-13T12:21:00Z). - Le finestre di energia (
period_start,period_end,timestamp_start,timestamp_end) sono ISO 8601 nel fuso dell'impianto, con il relativo offset (2026-10-13T00:00:00+02:00). - Lo stato di carica è per gateway, mai una media d'impianto.
Ogni quanto si aggiornano i dati
| Dati | Come vengono prodotti | Conseguenza pratica |
|---|---|---|
| Potenza | un campione per gateway ogni 60 s | interrogare più spesso restituisce lo stesso campione |
| Stato online | dati ricevuti negli ultimi 5 minuti | un impianto diventa offline 5 minuti dopo l'ultimo campione |
| Energia | contatori a 15 minuti | i totali del giorno arrivano con circa 15 minuti di ritardo |
La regola del null su telemetry/latest
telemetry/latest restituisce solo campioni degli ultimi 5 minuti. Se l'impianto non ha inviato dati in quel tempo, la risposta è comunque 200, con "timestamp": null e "measurements": null: un valore vecchio non viene mai restituito. Un null quindi significa "nessun dato recente", non "zero"; per sapere da quando l'impianto tace guarda last_seen_at nella connettività.
Dentro measurements, pv_power_w e load_power_w valgono 0 negli impianti che non li misurano; sono null solo nei campioni di telemetry/series. Gestisci sempre il null come valore possibile per potenze, stati di carica ed energie.
Polling consigliato
Schema per una flotta fino a 100 impianti, cioè una pagina bulk:
| Chiamata | Intervallo | Richieste al giorno |
|---|---|---|
GET /v1/telemetry/latest |
60 s | 1 440 |
GET /v1/connectivity |
5 min | 288 |
GET /v1/energy/totals?period=day |
15 min | 96 |
| Totale | ≈ 1 800 |
- Intervalli più brevi non danno dati più freschi: restituiscono gli stessi campioni.
- Leggi serie di potenza, serie di energia e allarmi per singolo impianto solo quando servono.
- Ogni pagina bulk in più moltiplica le richieste: oltre 100 impianti questo schema supera il limite giornaliero (vedi "Limiti, errori e supporto"), quindi allunga gli intervalli o chiedi un accordo dedicato.