Graaddagen-API

Graaddagen#

Parameters

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

Wat een graaddag is, in één alinea

Een verwarmingsgraaddag meet hoe ver onder een basistemperatuur de buitenlucht bleef, en hoe lang. Bij basis 18 °C draagt een uur op 16 °C (18 − 16) / 24 = 0.083 verwarmingsgraaddagen bij. Tel de uren op en u hebt een getal dat evenredig is met de energie die een gebouw nodig had. Koelgraaddagen zijn het spiegelbeeld: hoe ver boven de basis. Het is de gangbare manier om het ene stookseizoen met het andere te vergelijken nadat het weer uit de vergelijking is gehaald.

Veel basiswaarden, één verzoek, één prijs#

Het lezen en decoderen van de uurreeks vormt de volledige kostprijs van een graaddagen-antwoord. Zodra die array in het geheugen staat, is een extra basiswaarde slechts een aftrekking erover: er zestig opvragen kost wat er één opvragen kost.

Het antwoord krijgt een by_base-array met elke basiswaarde in de volgorde waarin u ze hebt opgesomd. totals en breakdown blijven de eerste beschrijven, zodat code die vóór dit bestond nog ongewijzigd werkt.

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

Handig wanneer u nog niet weet welke basiswaarde de cijfers van een contract reproduceert, of wanneer hetzelfde gebouw door verschillende partijen op verschillende basiswaarden wordt afgerekend — een verhuurder op 15,5 en een energieleverancier op 18 hebben allebei gelijk, en dit geeft beide in één aanroep terug.

Rekenmethoden#

De methode is een parameter omdat uw contract dat beslist, niet wij. Dezelfde data, dezelfde basis, hetzelfde jaar, in Algiers:

eurostat negeert base volledig: de definitie legt haar eigen drempels vast, en uw parameter honoreren zou een getal opleveren dat geen Eurostat-graaddag is terwijl het beweert er een te zijn.

/v1/methods heeft geen sleutel nodig. Gebruik het om een methodekiezer in uw interface te vullen zonder iets uit te geven, en zonder een lijst hard in te coderen die veroudert.

Graaddagen per stad#

Past twee correcties toe die een kale coördinaat niet toelaat: de tijdzone van de stad, zodat dagen lokaal worden afgesneden, en haar gekalibreerde stedelijk-hitte-eilandverschuiving.

De heranalyse leest bebouwde gebieden 1 tot 3 °C te laag. Dat vertekent koelgraaddagen naar beneden — relevant als u een airconditioning dimensioneert, en onzichtbaar als u niet weet dat u ernaar moet zoeken.

Graaddagen voor uw gebouw, niet voor de rastercel#

Een weerstation staat op de hoogte waar het staat, en niemand kan het 600 m hoger tegen de dalwand voor u verplaatsen. Onze bron is een model: de maaiveldhoogte van de cel is dus een getal in het archief, en het verschil is rekenwerk — 0,65 °C per 100 m. Over een stookseizoen is dat geen afrondingsfout.

Op uitdrukkelijk verzoek, en het antwoord zegt precies wat het heeft gedaan:

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

Het voorbehoud reist mee in het antwoord in plaats van alleen op deze pagina te staan, omdat degene die die JSON over zes maanden leest niet degene is die de documentatie heeft gelezen.

Een cel vastzetten, zodat een basislijn vergelijkbaar blijft#

Elke andere manier om een locatie aan te duiden start de zoektocht naar de dichtstbijzijnde cel bij elk verzoek opnieuw: het antwoord hangt dus af van wat het archief vandaag bevat. Dat is de juiste standaard voor een eenmalige opzoeking, en de verkeerde voor een basislijn — een vergelijking over meerdere jaren is alleen een vergelijking als elk jaar van dezelfde plek komt.

Naarmate het archief zich uitbreidt verandert de dichtstbijzijnde cel bij een gegeven locatie — een verbetering van de dekking die anders als een onverklaarde stap in uw data zou binnenkomen.

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

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

distance_km is 0 bij een vastgezet verzoek, per constructie: u hebt de cel benoemd, dus er is niets voor in de plaats gezet. Een cel die niet meer bestaat geeft 404 cell_not_found terug in plaats van stilletjes terug te vallen op een buur — wat precies de vervanging zou herintroduceren die u met vastzetten wilde vermijden.

Uitsplitsingsperioden#

Elk graaddagen-antwoord draagt een breakdown-array die is geaggregeerd naar de periode die u opvraagt. Contracten rekenen op verschillende perioden af, dus alle vier zijn beschikbaar op hetzelfde verzoek voor dezelfde prijs.

Elke emmer draagt daarnaast days, zodat een gedeeltelijke maand aan de rand van uw bereik zichtbaar is in plaats van stilletjes te kort. Een februari met "days": 12 is een februari die u niet met een volledige moet vergelijken.

Maandtotalen voor een jaar#

Een kortere weg voor het gangbare geval: ?lat=&lon=&year=2025 en er komen twaalf rijen terug. Dezelfde data als /v1/degree-days?breakdown=monthly over hetzelfde bereik; minder parameters om fout te doen.

/v1/coverage meldt de eerste en laatste dag van het archief en de resolutie ervan, heeft geen sleutel nodig, en is het juiste om te controleren voordat u een periode dicht bij de huidige rand opvraagt — ERA5-Land loopt ongeveer vijf dagen achter, en provisional_days in uw antwoord is daarvan het gevolg.

{
  "start": "1950-01-01",
  "end": "2026-07-29",        // laatste dag die data BEVAT
  "axis_end": "2026-12-31",   // waar deze run zal ophouden te groeien
  "hours": 671256, "axis_hours": 674976,
  "cells": 86274, "resolution_km": 9.0,
  "run": "world-1950-2026-p1000"
}

CSV-export#

Voeg format=csv toe aan elk graaddagen-verzoek. U krijgt de breakdown-rijen als CSV-bestand, genoemd naar de locatie en de data, zodat het zes maanden later in een downloadmap nog herkenbaar is.

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

Alleen betaalde abonnementen, en begrensd: hetzelfde maximale bereik als een JSON-verzoek, alleen geaggregeerde rijen — nooit de uurreeks — en het kost vier credits voor elke credit die de gelijkwaardige JSON-aanroep kost. Een gratis sleutel krijgt 402 export_not_in_plan.

Dat is opzet, en niet met tegenzin toegestaan. Waar u voor betaalt is het archief, en een onbegrensde export is de manier waarop een concurrent het op één middag verwerft. Juist die grenzen maken dat het formaat überhaupt kan bestaan.

Uurlijkse historie#

Parameters

Hetzelfde archief waaruit de graaddagen worden opgebouwd, rechtstreeks geleverd: uurlijks, tot 1950, op een raster van 9 km, overal op het land. Dezelfde host en dezelfde dju-scope — wie graaddagen kan aanroepen, kan dit ook aanroepen.

Voor dagwaarden over een lange periode, of voor normalen en trends, gebruik in plaats daarvan de Klimaat-API — die houdt de dagvelden al afgeleid bij, heeft geen grens bij 9 km of 1950, en beantwoordt een hele klimatologie in één aanroep.

Historie per stad#

Twee dingen die een coördinaat niet kan dragen: de tijdzone van de stad, zodat de dagen worden afgesneden waar de stad ze werkelijk beleeft, en haar gekalibreerde stedelijk-hitte-eilandcorrectie. daily staat hier standaard op true, omdat een stadsverzoek vrijwel altijd een verzoek over dagen is.

Beschikbare variabelen#

Somt op wat het archief op dit moment bevat, met eenheden, en welke velden afgeleid zijn in plaats van opgeslagen. Een archief dat alleen voor graaddagen is ingenomen bevat uitsluitend de temperatuur, en dit endpoint zegt dat ronduit in plaats van kolommen null terug te geven.