API Grade-zile

Grade-zile#

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 } ]
}

Ce este un grad-zi, într-un paragraf

Un grad-zi de încălzire măsoară cât de mult sub o temperatură de bază a stat aerul de afară și cât timp. La baza 18 °C, o oră la 16 °C contribuie cu (18 − 16) / 24 = 0.083 HDD. Însumați orele și aveți un număr proporțional cu energia de care a avut nevoie o clădire. Gradele-zile de răcire sunt oglinda: cât de mult peste bază. E modul standard de a compara un sezon de încălzire cu altul, după ce vremea a fost scoasă din comparație.

Mai multe baze, o cerere, un preț#

Citirea și decodarea seriei orare reprezintă tot costul unui răspuns de grade-zile. Odată ce vectorul acela e în memorie, încă o bază e o scădere peste el, deci a cere șaizeci costă cât a cere una.

Răspunsul câștigă un vector by_base care poartă toate bazele în ordinea în care le-ați enumerat. totals și breakdown descriu în continuare prima, deci codul scris înainte ca asta să existe funcționează neschimbat.

"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}
]

Util când nu știți încă ce bază reproduce cifrele unui contract sau când aceeași clădire e decontată la baze diferite de părți diferite — un proprietar pe 15,5 și un furnizor de energie pe 18 au amândoi dreptate, iar asta le întoarce pe amândouă într-un singur apel.

Metode de calcul#

Metoda e un parametru pentru că o decide contractul dumneavoastră, nu noi. Aceleași date, aceeași bază, același an, la Alger:

eurostat ignoră complet base: definiția își fixează propriile praguri, iar respectarea parametrului dumneavoastră ar produce un număr care nu e un grad-zi Eurostat, dar care ar pretinde că este.

/v1/methods nu cere cheie. Folosiți-l ca să populați un selector de metode în interfața dumneavoastră fără să cheltuiți nimic și fără să fixați în cod o listă care se va învechi.

Grade-zile pe oraș#

Aplică două corecții pe care o coordonată simplă nu le poate face: fusul orar al orașului, ca zilele să fie tăiate local, și decalajul calibrat al insulei de căldură urbană.

Reanaliza subestimează zonele construite cu 1–3 °C. Asta trage în jos gradele-zile de răcire — important dacă dimensionați aer condiționat, și invizibil dacă nu știți că trebuie să căutați.

Grade-zile pentru clădirea dumneavoastră, nu pentru celula de grilă#

O stație meteo se află la altitudinea la care se află și nimeni nu o poate muta 600 m mai sus pe versantul văii pentru dumneavoastră. Sursa noastră e un model, deci altitudinea terenului din celulă e un număr în arhivă, iar diferența e aritmetică: 0,65 °C la fiecare 100 m. Pe un sezon de încălzire, asta nu e o eroare de rotunjire.

Se activează la cerere, iar răspunsul spune exact ce a făcut:

"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."
}

Avertismentul călătorește în răspuns, nu doar pe pagina asta, pentru că cine va citi JSON-ul peste șase luni nu e cine a citit documentația.

Fixarea unei celule, ca o referință să rămână comparabilă#

Toate celelalte forme de localizare reiau căutarea celei mai apropiate celule la fiecare cerere, deci răspunsul depinde de ce conține arhiva azi. E valoarea implicită potrivită pentru o consultare izolată și cea nepotrivită pentru o referință: o comparație pe mai mulți ani e o comparație doar dacă fiecare an vine din același loc.

Pe măsură ce arhiva se lărgește, celula cea mai apropiată de un sit dat se schimbă — o îmbunătățire de acoperire care altfel ar ajunge în datele dumneavoastră ca un salt inexplicabil.

# o dată, la configurare
GET /v1/cells/resolve?lat=45.19&lon=5.72
  → { "id": "era5l_45.20_5.70", "distance_km": 1.4, "resolution_km": 9 }

# de fiecare dată după aceea
GET /v1/degree-days/cell/era5l_45.20_5.70?base=18&start=2015-01-01&end=2025-12-31

distance_km este 0 într-o cerere fixată prin construcție: ați numit celula, deci nimic nu a fost înlocuit. O celulă care nu mai există întoarce 404 cell_not_found în loc să cadă tăcut pe una vecină — ceea ce ar reintroduce exact substituția pe care ați fixat-o ca s-o evitați.

Perioade de detaliere#

Fiecare răspuns de grade-zile poartă un vector breakdown agregat la perioada pe care o cereți. Contractele se decontează pe perioade diferite, deci toate patru sunt disponibile în aceeași cerere, la același preț.

Fiecare interval poartă și days, ca o lună parțială la marginea intervalului dumneavoastră să fie vizibilă, nu tăcut mai scurtă. Un februarie cu "days": 12 e un februarie pe care n-ar trebui să-l comparați cu unul întreg.

Totaluri lunare pentru un an#

O scurtătură pentru cazul obișnuit: ?lat=&lon=&year=2025 și se întorc douăsprezece rânduri. Aceleași date ca /v1/degree-days?breakdown=monthly pe același interval; mai puțini parametri de greșit.

/v1/coverage raportează prima și ultima zi a arhivei și rezoluția ei, nu cere cheie și e lucrul potrivit de verificat înainte să cereți o perioadă aproape de marginea prezentului — ERA5-Land e în urmă cu vreo cinci zile, iar provisional_days din răspunsul dumneavoastră e consecința.

{
  "start": "1950-01-01",
  "end": "2026-07-29",        // ultima zi care CONȚINE date
  "axis_end": "2026-12-31",   // unde se va opri din creștere această rulare
  "hours": 671256, "axis_hours": 674976,
  "cells": 86274, "resolution_km": 9.0,
  "run": "world-1950-2026-p1000"
}

Export CSV#

Adăugați format=csv la orice cerere de grade-zile. Primiți rândurile din breakdown ca fișier CSV, denumit după loc și date, astfel încât să fie încă recognoscibil peste șase luni într-un folder de descărcări.

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

Doar planuri plătite, și limitat: același interval maxim ca la o cerere JSON, doar rânduri agregate — niciodată seria orară — și costă patru credite pentru fiecare unul pe care îl costă apelul JSON echivalent. O cheie gratuită primește 402 export_not_in_plan.

Asta e o alegere deliberată, nu o cârcoteală. Arhiva e ceea ce plătiți, iar un export nelimitat e felul în care un concurent și-o însușește într-o după-amiază. Limitele sunt cele care fac posibilă existența formatului.

Istoric orar#

Parametri

Aceeași arhivă din care sunt construite gradele-zile, servită direct: orar, din 1950, pe o grilă de 9 km, peste tot pe uscat. Aceeași gazdă și același scope dju — dacă puteți apela gradele-zile, puteți apela și asta.

Pentru valori zilnice pe o perioadă lungă, sau pentru normale și tendințe, folosiți în schimb API-ul Climă — conține câmpurile zilnice deja derivate, nu are limita de 9 km/1950 și răspunde cu o climatologie întreagă într-un singur apel.

Istoric pe oraș#

Două lucruri pe care o coordonată nu le poate purta: fusul orar al orașului, ca zilele să fie tăiate acolo unde orașul le trăiește cu adevărat, și corecția lui calibrată de insulă de căldură urbană. Aici daily e implicit true, pentru că o cerere pe oraș e aproape mereu o cerere despre zile.

Variabile disponibile#

Enumeră ce conține arhiva chiar acum, cu unități, și care câmpuri sunt derivate în loc să fie stocate. O arhivă ingerată doar pentru grade-zile conține numai temperatură, iar endpointul acesta o spune limpede în loc să întoarcă coloane de null.