API Gradi giorno

Gradi giorno#

Parametri

{
  "location": {
    "latitude": 36.75, "longitude": 3.06,
    "grid_cell": { "latitude": 36.7, "longitude": 3.1,
                   "distance_km": 6.61, "resolution_km": 9 }
  },
  "parameters": {
    "base_temperature_c": 18.0, "method": "hourly",
    "start": "2025-07-01", "end": "2026-06-30"
  },
  "totals": { "hdd": 781.86, "cdd": 1331.61 },
  "quality": {
    "days": 365, "coverage": 1.0,
    "missing_hours": 0, "provisional_days": 0
  },
  "breakdown": [ { "year": 2025, "month": 7, "hdd": 0.0, "cdd": 289.4, "days": 31 } ]
}

Che cos'è un grado giorno, in un paragrafo

Un grado giorno di riscaldamento misura quanto l'aria esterna sia rimasta sotto una temperatura di base, e per quanto tempo. A base 18 °C, un'ora a 16 °C apporta (18 − 16) / 24 = 0.083 GG di riscaldamento. Sommi le ore e avrà una cifra proporzionale all'energia di cui un edificio ha avuto bisogno. I gradi giorno di raffrescamento sono lo specchio: quanto sopra la base. È il modo standard di confrontare una stagione di riscaldamento con un'altra una volta tolta la meteorologia dal confronto.

Molte basi, una richiesta, un solo prezzo#

Leggere e decodificare la serie oraria costituisce l'intero costo di una risposta sui gradi giorno. Una volta che quell'array è in memoria, una base in più è solo una sottrazione su di esso: chiederne sessanta costa quanto chiederne una.

La risposta guadagna un array by_base che porta ogni base nell'ordine in cui le ha elencate. totals e breakdown continuano a descrivere la prima, così il codice scritto prima che questo esistesse funziona ancora immutato.

"by_base": [
  {"base": 15.0,  "hdd": 402.11, "cdd": 1731.4},
  {"base": 15.5,  "hdd": 431.02, "cdd": 1706.3},
  {"base": 18.0,  "hdd": 781.86, "cdd": 1331.6}
]

Utile quando non sa ancora quale base riproduce le cifre di un contratto, o quando lo stesso edificio è liquidato con basi diverse da parti diverse — un locatore su 15,5 e un fornitore di energia su 18 hanno entrambi ragione, e questo restituisce entrambe in una sola chiamata.

Metodi di calcolo#

Il metodo è un parametro perché lo decide il suo contratto, non noi. Stessi dati, stessa base, stesso anno, ad Algeri:

eurostat ignora del tutto base: la definizione fissa le proprie soglie, e onorare il suo parametro produrrebbe una cifra che non è un grado giorno Eurostat pur pretendendo di esserlo.

/v1/methods non richiede chiave. Lo usi per popolare un selettore di metodo nella sua interfaccia senza spendere nulla e senza scrivere a codice un elenco che diventerà obsoleto.

Gradi giorno per città#

Applica due correzioni che una coordinata nuda non consente: il fuso orario della città, perché le giornate siano tagliate localmente, e il suo scarto per isola di calore urbana calibrato.

La rianalisi sottostima le aree edificate di 1–3 °C. Questo distorce verso il basso i gradi giorno di raffrescamento — rilevante se sta dimensionando un condizionamento, e invisibile se non sa di doverlo cercare.

Gradi giorno per il suo edificio, non per la cella della griglia#

Una stazione meteorologica è alla quota in cui si trova, e nessuno può spostarla 600 m più in alto sul versante per lei. La nostra fonte è un modello: la quota del suolo della cella è quindi una cifra nell'archivio, e la differenza è aritmetica — 0,65 °C ogni 100 m. Su una stagione di riscaldamento non è un errore di arrotondamento.

Su richiesta esplicita, e la risposta dice esattamente cosa ha fatto:

"elevation": {
  "applied": true,
  "model_elevation_m": 42.0,
  "location_elevation_m": 1200,
  "temperature_offset_c": -7.53,
  "caveat": "Lapse-rate correction. It assumes temperature falls smoothly with
             height, which a valley floor under a winter inversion does not."
}

L'avvertenza viaggia nella risposta anziché soltanto su questa pagina, perché chi leggerà quel JSON fra sei mesi non è chi ha letto la documentazione.

Fissare una cella, perché una linea di base resti confrontabile#

Ogni altro modo di indicare un luogo rilancia la ricerca della cella più vicina a ogni richiesta: la risposta dipende quindi da ciò che l'archivio contiene oggi. È l'impostazione giusta per una consultazione occasionale, e quella sbagliata per una linea di base — un confronto su più anni è un confronto solo se ogni anno proviene dallo stesso posto.

Man mano che l'archivio si allarga, la cella più vicina a un dato sito cambia — un miglioramento della copertura che altrimenti arriverebbe nei suoi dati come un gradino inspiegato.

# una volta, all'installazione
GET /v1/cells/resolve?lat=45.19&lon=5.72
  → { "id": "era5l_45.20_5.70", "distance_km": 1.4, "resolution_km": 9 }

# ogni volta successiva
GET /v1/degree-days/cell/era5l_45.20_5.70?base=18&start=2015-01-01&end=2025-12-31

distance_km vale 0 su una richiesta fissata per costruzione: lei ha nominato la cella, quindi nulla le è stato sostituito. Una cella che non esiste più restituisce 404 cell_not_found anziché ripiegare in silenzio su una vicina — il che reintrodurrebbe proprio la sostituzione che fissandola voleva evitare.

Periodi di ripartizione#

Ogni risposta sui gradi giorno porta un array breakdown aggregato al periodo che lei chiede. I contratti si liquidano su periodi diversi, quindi tutti e quattro sono disponibili sulla stessa richiesta allo stesso prezzo.

Ogni intervallo porta inoltre days, così un mese parziale al bordo del suo intervallo è visibile anziché silenziosamente corto. Un febbraio con "days": 12 è un febbraio che non dovrebbe confrontare con uno completo.

Totali mensili di un anno#

Una scorciatoia per il caso comune: ?lat=&lon=&year=2025 e tornano dodici righe. Stessi dati di /v1/degree-days?breakdown=monthly sullo stesso intervallo; meno parametri da sbagliare.

/v1/coverage riporta il primo e l'ultimo giorno dell'archivio e la sua risoluzione, non richiede chiave, ed è la cosa giusta da controllare prima di chiedere un periodo vicino al bordo presente — ERA5-Land è indietro di circa cinque giorni, e provisional_days nella sua risposta ne è la conseguenza.

{
  "start": "1950-01-01",
  "end": "2026-07-29",        // ultimo giorno che CONTIENE dati
  "axis_end": "2026-12-31",   // dove questa corsa smetterà di crescere
  "hours": 671256, "axis_hours": 674976,
  "cells": 86274, "resolution_km": 9.0,
  "run": "world-1950-2026-p1000"
}

Esportazione CSV#

Aggiunga format=csv a qualsiasi richiesta sui gradi giorno. Otterrà le righe di breakdown come file CSV, con un nome basato sul luogo e sulle date, così da restare identificabile sei mesi dopo in una cartella di download.

year,month,hdd,cdd,days,t_mean,coverage,provisional
2024,1,205.03,2.88,31,11.48,1.0,false
2024,2,168.44,4.10,29,12.31,1.0,false

Solo piani a pagamento, e limitato: lo stesso intervallo massimo di una richiesta JSON, solo righe aggregate — mai la serie oraria — e costa quattro crediti per ognuno che costa la chiamata JSON equivalente. Una chiave gratuita riceve 402 export_not_in_plan.

È deliberato, non concesso a malincuore. Ciò che lei paga è l'archivio, e un'esportazione senza limiti è il modo in cui un concorrente se lo procura in un pomeriggio. Sono questi limiti a permettere che il formato esista.

Storico orario#

Parametri

Lo stesso archivio da cui sono costruiti i gradi giorno, servito direttamente: orario, fino al 1950, su una griglia di 9 km, ovunque sulle terre emerse. Stesso host e stesso scope dju — se può chiamare i gradi giorno, può chiamare anche questo.

Per valori giornalieri su un lungo periodo, o per normali e tendenze, usi piuttosto l'API Clima — tiene i campi giornalieri già derivati, non ha alcun confine a 9 km né al 1950, e risponde a un'intera climatologia in una sola chiamata.

Storico per città#

Due cose che una coordinata non può portare: il fuso orario della città, perché le giornate siano tagliate dove la città le vive davvero, e la sua correzione calibrata per isola di calore urbana. daily vale true per impostazione predefinita qui, perché una richiesta per città è quasi sempre una richiesta su giornate.

Variabili disponibili#

Elenca ciò che l'archivio contiene in questo momento, con le unità, e quali campi sono derivati anziché memorizzati. Un archivio ingerito per i soli gradi giorno contiene solo la temperatura, e questo endpoint lo dice apertamente anziché restituire colonne di null.