Gradtag-API

Gradtage#

Parameter

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

Was ein Gradtag ist, in einem Absatz

Ein Heizgradtag misst, wie weit unter einer Basistemperatur die Außenluft lag und wie lange. Bei Basis 18 °C trägt eine Stunde bei 16 °C (18 − 16) / 24 = 0.083 Heizgradtage bei. Summieren Sie die Stunden, und Sie haben eine Zahl, die zur Energie proportional ist, die ein Gebäude brauchte. Kühlgradtage sind das Spiegelbild: wie weit über der Basis. Es ist die übliche Art, eine Heizperiode mit einer anderen zu vergleichen, nachdem das Wetter aus dem Vergleich herausgerechnet wurde.

Viele Basiswerte, eine Anfrage, ein Preis#

Die Stundenreihe zu lesen und zu dekodieren macht die gesamten Kosten einer Gradtag-Antwort aus. Sobald dieses Feld im Speicher liegt, ist ein weiterer Basiswert nur noch eine Subtraktion darüber: sechzig anzufragen kostet also so viel wie einen.

Die Antwort erhält ein by_base-Feld, das jeden Basiswert in der von Ihnen genannten Reihenfolge trägt. totals und breakdown beschreiben weiterhin den ersten, sodass Code, der vor dieser Möglichkeit geschrieben wurde, unverändert funktioniert.

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

Nützlich, wenn Sie noch nicht wissen, welcher Basiswert die Zahlen eines Vertrags reproduziert, oder wenn dasselbe Gebäude von verschiedenen Parteien mit verschiedenen Basiswerten abgerechnet wird — ein Vermieter mit 15,5 und ein Energieversorger mit 18 haben beide recht, und dies liefert beides in einem Aufruf.

Berechnungsmethoden#

Die Methode ist ein Parameter, weil Ihr Vertrag sie bestimmt, nicht wir. Dieselben Daten, derselbe Basiswert, dasselbe Jahr, in Algier:

eurostat ignoriert base vollständig: die Definition legt ihre eigenen Schwellen fest, und Ihren Parameter zu beachten ergäbe eine Zahl, die kein Eurostat-Gradtag ist, sich aber als einer ausgibt.

/v1/methods braucht keinen Schlüssel. Nutzen Sie es, um in Ihrer Oberfläche eine Methodenauswahl zu füllen, ohne etwas auszugeben und ohne eine Liste fest einzuschreiben, die veraltet.

Gradtage nach Stadt#

Wendet zwei Korrekturen an, die eine nackte Koordinate nicht erlaubt: die Zeitzone der Stadt, damit die Tage lokal geschnitten werden, und ihren kalibrierten Wärmeinsel-Versatz.

Die Reanalyse liest bebaute Flächen um 1 bis 3 °C zu niedrig. Das verzerrt Kühlgradtage nach unten — erheblich, wenn Sie eine Klimaanlage auslegen, und unsichtbar, wenn Sie nicht wissen, dass Sie danach suchen müssen.

Gradtage für Ihr Gebäude, nicht für die Gitterzelle#

Eine Wetterstation steht auf der Höhe, auf der sie steht, und niemand kann sie für Sie 600 m den Hang hinauf versetzen. Unsere Quelle ist ein Modell: die Geländehöhe der Zelle ist also eine Zahl im Archiv, und die Differenz ist Arithmetik — 0,65 °C je 100 m. Über eine Heizperiode ist das kein Rundungsfehler.

Nur auf ausdrücklichen Wunsch, und die Antwort sagt genau, was sie getan hat:

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

Der Vorbehalt reist in der Antwort mit statt nur auf dieser Seite zu stehen, weil die Person, die dieses JSON in sechs Monaten liest, nicht die ist, die die Dokumentation gelesen hat.

Eine Zelle fixieren, damit eine Basislinie vergleichbar bleibt#

Jede andere Ortsangabe startet die Suche nach der nächsten Zelle bei jeder Anfrage neu: die Antwort hängt also davon ab, was das Archiv heute enthält. Für eine einmalige Abfrage ist das die richtige Voreinstellung, für eine Basislinie die falsche — ein Vergleich über mehrere Jahre ist nur dann ein Vergleich, wenn jedes Jahr vom selben Ort stammt.

Mit wachsendem Archiv ändert sich die nächstgelegene Zelle zu einem bestimmten Standort — eine Verbesserung der Abdeckung, die sonst als unerklärlicher Sprung in Ihren Daten ankäme.

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

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

distance_km ist bei einer fixierten Anfrage konstruktionsbedingt 0: Sie haben die Zelle benannt, es wurde also nichts für sie eingesetzt. Eine Zelle, die es nicht mehr gibt, liefert 404 cell_not_found, statt stillschweigend auf eine Nachbarzelle auszuweichen — was genau die Ersetzung wieder einführte, zu deren Vermeidung Sie fixiert haben.

Aufschlüsselungszeiträume#

Jede Gradtag-Antwort trägt ein breakdown-Feld, das auf den von Ihnen gewünschten Zeitraum aggregiert ist. Verträge rechnen auf verschiedenen ab, alle vier stehen deshalb bei derselben Anfrage zum selben Preis zur Verfügung.

Jeder Eimer trägt außerdem days, sodass ein angebrochener Monat am Rand Ihres Bereichs sichtbar ist statt stillschweigend zu kurz. Ein Februar mit "days": 12 ist ein Februar, den Sie nicht mit einem vollständigen vergleichen sollten.

Monatssummen für ein Jahr#

Eine Kurzform für den häufigen Fall: ?lat=&lon=&year=2025, und zwölf Zeilen kommen zurück. Dieselben Daten wie /v1/degree-days?breakdown=monthly über dieselbe Spanne; weniger Parameter, bei denen man sich vertun kann.

/v1/coverage meldet den ersten und letzten Tag des Archivs sowie seine Auflösung, braucht keinen Schlüssel und ist das Richtige, um es zu prüfen, bevor Sie einen Zeitraum nahe der Gegenwart anfragen — ERA5-Land hinkt etwa fünf Tage hinterher, und provisional_days in Ihrer Antwort ist die Folge.

{
  "start": "1950-01-01",
  "end": "2026-07-29",        // letzter Tag, der Daten ENTHÄLT
  "axis_end": "2026-12-31",   // wo dieser Lauf aufhören wird zu wachsen
  "hours": 671256, "axis_hours": 674976,
  "cells": 86274, "resolution_km": 9.0,
  "run": "world-1950-2026-p1000"
}

CSV-Export#

Hängen Sie format=csv an eine beliebige Gradtag-Anfrage an. Sie erhalten die breakdown-Zeilen als CSV-Datei, benannt nach Ort und Daten, sodass sie sechs Monate später in einem Download-Ordner noch erkennbar ist.

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

Nur bezahlte Tarife, und begrenzt: dieselbe Höchstspanne wie bei einer JSON-Anfrage, nur aggregierte Zeilen — niemals die Stundenreihe — und es kostet vier Credits für jeden, den der entsprechende JSON-Aufruf kostet. Ein kostenloser Schlüssel bekommt 402 export_not_in_plan.

Das ist bewusst so und nicht widerwillig. Bezahlt wird für das Archiv, und ein unbegrenzter Export ist der Weg, auf dem ein Wettbewerber es sich an einem Nachmittag beschafft. Erst diese Grenzen erlauben es, das Format überhaupt anzubieten.

Stündliche Historie#

Parameter

Dasselbe Archiv, aus dem die Gradtage gebaut sind, direkt ausgeliefert: stündlich, zurück bis 1950, auf einem 9-km-Gitter, überall an Land. Gleicher Host und gleicher dju-Scope — wer Gradtage aufrufen kann, kann auch dies aufrufen.

Für Tageswerte über einen langen Zeitraum oder für Normalwerte und Trends nehmen Sie stattdessen die Klima-API — sie hält die Tagesfelder bereits abgeleitet vor, hat keine 9-km-/1950-Grenze und beantwortet eine ganze Klimatologie in einem Aufruf.

Historie nach Stadt#

Zwei Dinge, die eine Koordinate nicht tragen kann: die Zeitzone der Stadt, damit die Tage dort geschnitten werden, wo die Stadt sie tatsächlich erlebt, und ihre kalibrierte Wärmeinselkorrektur. daily steht hier standardmäßig auf true, weil eine Stadt-Anfrage fast immer eine Anfrage über Tage ist.

Verfügbare Variablen#

Listet auf, was das Archiv gerade jetzt enthält, mit Einheiten, und welche Felder abgeleitet statt gespeichert sind. Ein allein für Gradtage aufgenommenes Archiv enthält nur die Temperatur, und dieser Endpunkt sagt das geradeheraus, statt Spalten voller null zurückzugeben.