API Stopniodni

Stopniodni#

Parametry

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

Czym jest stopniodzień, w jednym akapicie

Stopniodzień grzania mierzy, jak głęboko poniżej temperatury bazowej znajdowało się powietrze na zewnątrz i jak długo. Przy bazie 18 °C godzina przy 16 °C wnosi (18 − 16) / 24 = 0.083 HDD. Zsumuj godziny, a masz liczbę proporcjonalną do energii, której potrzebował budynek. Stopniodni chłodzenia są lustrem: jak wysoko powyżej bazy. To standardowy sposób porównywania jednego sezonu grzewczego z drugim po wyjęciu pogody z porównania.

Wiele baz, jedno żądanie, jedna cena#

Odczyt i zdekodowanie szeregu godzinowego to cały koszt odpowiedzi o stopniodniach. Gdy ta tablica jest już w pamięci, kolejna baza to odejmowanie na niej, więc poproszenie o sześćdziesiąt kosztuje tyle, co poproszenie o jedną.

Odpowiedź zyskuje tablicę by_base niosącą wszystkie bazy w kolejności, w jakiej je wymieniłeś. totals i breakdown nadal opisują pierwszą, więc kod napisany, zanim to powstało, działa bez zmian.

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

Przydatne, gdy nie wiesz jeszcze, która baza odtwarza liczby z umowy, albo gdy ten sam budynek jest rozliczany na różnych bazach przez różne strony — właściciel na 15,5 i dostawca energii na 18 mają obaj rację, a to zwraca obie w jednym wywołaniu.

Metody obliczeń#

Metoda jest parametrem, bo decyduje o niej twoja umowa, a nie my. Te same dane, ta sama baza, ten sam rok, w Algierze:

eurostat całkowicie ignoruje base: definicja ustala własne progi, a uszanowanie twojego parametru dałoby liczbę, która nie jest stopniodniem Eurostatu, choć twierdziłaby, że jest.

/v1/methods nie wymaga klucza. Użyj go, żeby wypełnić listę wyboru metody w swoim interfejsie bez wydawania czegokolwiek i bez zaszywania w kodzie listy, która się zdezaktualizuje.

Stopniodni dla miasta#

Stosuje dwie korekty, których goła współrzędna nie potrafi: strefę czasową miasta, dzięki czemu dni są cięte lokalnie, oraz jego skalibrowaną poprawkę na miejską wyspę ciepła.

Reanaliza zaniża tereny zabudowane o 1–3 °C. To zaniża stopniodni chłodzenia — rzecz istotna, jeśli dobierasz klimatyzację, i niewidoczna, jeśli nie wiesz, że trzeba jej szukać.

Stopniodni dla twojego budynku, a nie dla komórki siatki#

Stacja meteorologiczna stoi na wysokości, na jakiej stoi, i nikt jej nie przeniesie 600 m wyżej po zboczu doliny. Naszym źródłem jest model, więc wysokość terenu komórki jest liczbą w archiwum, a różnica to arytmetyka: 0,65 °C na 100 m. W skali sezonu grzewczego nie jest to błąd zaokrąglenia.

Włączane na życzenie, a odpowiedź mówi dokładnie, co zrobiono:

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

Zastrzeżenie podróżuje w odpowiedzi, a nie tylko na tej stronie, bo osoba, która przeczyta ten JSON za pół roku, to nie ta sama osoba, która czytała dokumentację.

Przypięcie komórki, żeby punkt odniesienia pozostał porównywalny#

Każda inna forma lokalizacji przy każdym żądaniu na nowo szuka najbliższej komórki, więc odpowiedź zależy od tego, co archiwum zawiera dzisiaj. Dla jednorazowego sprawdzenia to właściwe zachowanie domyślne, a dla punktu odniesienia — błędne: porównanie wieloletnie jest porównaniem tylko wtedy, gdy każdy rok pochodzi z tego samego miejsca.

W miarę poszerzania archiwum najbliższa danej lokalizacji komórka się zmienia — poprawa pokrycia, która inaczej trafiłaby do twoich danych jako niewytłumaczony skok.

# raz, przy konfiguracji
GET /v1/cells/resolve?lat=45.19&lon=5.72
  → { "id": "era5l_45.20_5.70", "distance_km": 1.4, "resolution_km": 9 }

# za każdym kolejnym razem
GET /v1/degree-days/cell/era5l_45.20_5.70?base=18&start=2015-01-01&end=2025-12-31

distance_km w żądaniu przypiętym jest z założenia równe 0: nazwałeś komórkę, więc nic za nią nie podstawiono. Komórka, która już nie istnieje, zwraca 404 cell_not_found, zamiast po cichu cofnąć się do sąsiedniej — co przywróciłoby dokładnie to podstawienie, przed którym przypięcie chroni.

Okresy podziału#

Każda odpowiedź o stopniodniach niesie tablicę breakdown zagregowaną do okresu, o który poprosisz. Umowy rozliczają się na różnych, więc wszystkie cztery są dostępne w tym samym żądaniu i w tej samej cenie.

Każdy kubełek niesie też days, żeby niepełny miesiąc na krańcu twojego zakresu był widoczny, a nie po cichu krótszy. Luty z "days": 12 to luty, którego nie powinieneś porównywać z pełnym.

Sumy miesięczne dla roku#

Skrót dla częstego przypadku: ?lat=&lon=&year=2025 i wraca dwanaście wierszy. Te same dane co /v1/degree-days?breakdown=monthly na tym samym zakresie; mniej parametrów do pomylenia.

/v1/coverage raportuje pierwszy i ostatni dzień archiwum oraz jego rozdzielczość, nie wymaga klucza i jest tym, co warto sprawdzić przed poproszeniem o okres blisko krawędzi teraźniejszości — ERA5-Land jest opóźniony o jakieś pięć dni, a provisional_days w twojej odpowiedzi są tego konsekwencją.

{
  "start": "1950-01-01",
  "end": "2026-07-29",        // ostatni dzień, który MA dane
  "axis_end": "2026-12-31",   // gdzie ten przebieg przestanie rosnąć
  "hours": 671256, "axis_hours": 674976,
  "cells": 86274, "resolution_km": 9.0,
  "run": "world-1950-2026-p1000"
}

Eksport CSV#

Dodaj format=csv do dowolnego żądania o stopniodni. Dostajesz wiersze breakdown jako plik CSV, nazwany od lokalizacji i dat, żeby pół roku później w folderze pobranych nadal dało się go rozpoznać.

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

Tylko plany płatne, i z ograniczeniami: ten sam maksymalny zakres co przy żądaniu JSON, wyłącznie wiersze zagregowane — nigdy szereg godzinowy — a kosztuje cztery kredyty za każdy jeden, który kosztuje równoważne wywołanie JSON. Darmowy klucz dostaje 402 export_not_in_plan.

To jest celowe, a nie niechętne. Archiwum jest tym, za co płacisz, a eksport bez ograniczeń to sposób, w jaki konkurencja przejmuje je w jedno popołudnie. To właśnie ograniczenia pozwalają temu formatowi w ogóle istnieć.

Historia godzinowa#

Parametry

To samo archiwum, z którego budowane są stopniodni, serwowane wprost: godzinowo, od 1950 roku, na siatce 9 km, wszędzie na lądzie. Ten sam host i ten sam scope dju — jeśli możesz wywołać stopniodni, możesz wywołać i to.

Po wartości dobowe w długim okresie albo po normy i trendy sięgnij raczej po API Klimat — ma pola dobowe wyprowadzone z góry, nie ma granicy 9 km/1950 i odpowiada całą klimatologią w jednym wywołaniu.

Historia dla miasta#

Dwie rzeczy, których współrzędna nie niesie: strefa czasowa miasta, dzięki której dni są cięte tam, gdzie miasto naprawdę je przeżywa, oraz jego skalibrowana poprawka na miejską wyspę ciepła. daily jest tutaj domyślnie prawdą, bo żądanie o miasto to prawie zawsze żądanie o dni.

Dostępne zmienne#

Wypisuje, co archiwum zawiera w tej chwili, z jednostkami, oraz które pola są wyprowadzane, a nie przechowywane. Archiwum wciągnięte wyłącznie na potrzeby stopniodni zawiera samą temperaturę i ten endpoint mówi to wprost, zamiast zwracać kolumny null.