Degree Days API

Degree days#

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

What a degree day is, in one paragraph

A heating degree day measures how far below a base temperature the outside air sat, and for how long. At base 18 °C, an hour at 16 °C contributes (18 − 16) / 24 = 0.083 HDD. Sum the hours and you have a number proportional to the energy a building needed. Cooling degree days are the mirror: how far above the base. It is the standard way to compare one heating season with another after the weather has been taken out of the comparison.

Many bases, one request, one price#

Reading and decoding the hourly series is the entire cost of a degree-days answer. Once that array is in memory another base is a subtraction over it, so asking for sixty costs what asking for one costs.

The response gains a by_base array carrying every base in the order you listed them. totals and breakdown keep describing the first one, so code written before this existed still works unchanged.

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

Useful when you do not yet know which base reproduces a contract's figures, or when the same building is settled at different bases by different parties — a landlord on 15.5 and an energy supplier on 18 are both right, and this returns both in one call.

Calculation methods#

The method is a parameter because your contract decides it, not us. The same data, same base, same year, at Algiers:

eurostat ignores base entirely: the definition fixes its own thresholds, and honouring your parameter would produce a number that is not a Eurostat degree day while claiming to be one.

/v1/methods needs no key. Use it to populate a method picker in your UI without spending anything, and without hard-coding a list that will go stale.

Degree days by city#

Applies two corrections a bare coordinate cannot: the city's time zone, so days are cut locally, and its calibrated urban heat island offset.

Reanalysis under-reads built-up areas by 1–3 °C. That biases cooling degree days low — material if you are sizing air conditioning, and invisible if you do not know to look for it.

Degree days for your building, not for the grid cell#

A weather station is at the altitude it is at, and nobody can move it 600 m up the valley side for you. Our source is a model, so the cell's ground height is a number in the archive and the difference is arithmetic: 0.65 °C per 100 m. Over a heating season that is not a rounding error.

Opt-in, and the response says exactly what it did:

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

The caveat travels in the response rather than only on this page, because the person reading the JSON six months from now is not the person who read the documentation.

Pinning a cell, so a baseline stays comparable#

Every other location form re-runs the nearest-cell search on each request, so the answer depends on what the archive holds today. That is the right default for a one-off lookup, and the wrong one for a baseline: a multi-year comparison is only a comparison if each year comes from the same place.

As the archive widens, the nearest cell to a given site changes — an improvement in coverage that would otherwise arrive in your data as an unexplained step.

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

# every time after that
GET /v1/degree-days/cell/era5l_45.20_5.70?base=18&start=2015-01-01&end=2025-12-31

distance_km is 0 on a pinned request by construction: you named the cell, so nothing was substituted for it. A cell that no longer exists returns 404 cell_not_found rather than quietly falling back to a neighbour — which would reintroduce the very substitution you pinned it to avoid.

Breakdown periods#

Every degree-days response carries a breakdown array aggregated to the period you ask for. Contracts settle on different ones, so all four are available on the same request at the same price.

Every bucket also carries days, so a partial month at the edge of your range is visible rather than silently short. A February with "days": 12 is a February you should not compare against a full one.

Monthly totals for a year#

A shorthand for the common case: ?lat=&lon=&year=2025 and twelve rows come back. Same data as /v1/degree-days?breakdown=monthly over the same span; fewer parameters to get wrong.

/v1/coverage reports the archive's first and last day and its resolution, needs no key, and is the right thing to check before you ask for a period near the present edge — ERA5-Land runs about five days behind, and provisional_days in your response is the consequence.

{
  "start": "1950-01-01",
  "end": "2026-07-29",        // last day that HOLDS data
  "axis_end": "2026-12-31",   // where this run will stop growing
  "hours": 671256, "axis_hours": 674976,
  "cells": 86274, "resolution_km": 9.0,
  "run": "world-1950-2026-p1000"
}

CSV export#

Add format=csv to any degree-days request. You get the breakdown rows as a CSV file, named after the location and dates so it is still identifiable six months later in a downloads folder.

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

Paid plans only, and bounded: the same maximum span as a JSON request, aggregated rows only — never the hourly series — and it costs four credits for every one the equivalent JSON call costs. A free key gets 402 export_not_in_plan.

That is deliberate rather than grudging. The archive is what you are paying for, and an unbounded export is how a competitor acquires it in an afternoon. The bounds are what let the format exist at all.

Hourly history#

Parameters

The same archive the degree days are built from, served directly: hourly, back to 1950, on a 9 km grid, everywhere on land. Same host and same dju scope — if you can call degree days, you can call this.

For daily values over a long period, or for normals and trends, use the Climate API instead — it holds the daily fields pre-derived, has no 9 km/1950 boundary, and answers a whole climatology in one call.

History by city#

Two things a coordinate cannot carry: the city's time zone, so days are cut where the city actually experiences them, and its calibrated urban heat island correction. daily defaults to true here, because a city request is almost always a request about days.

Available variables#

Lists what the archive holds right now, with units, and which fields are derived rather than stored. An archive ingested for degree days alone holds temperature only, and this endpoint says so plainly instead of returning columns of null.