Degree Days API · ERA5-Land 9 km · 1950 →
Your base temperature. Not base 18.
A building with a 15.5 °C balance point cannot use an HDD18 figure. We keep the hourly temperature and integrate it against whatever base you ask for, at request time — which is the difference between a number you can bill on and a number you have to apologise for.
18.0
660
1 267
Algiers · one year of daily mean temperature Blue heating demand Orange cooling demand
The shaded area is the degree days. Drag the base and watch the two totals trade places — that trade is the whole reason the base has to be yours. This figure uses the daily-mean method so it can run in your browser; the API integrates the hourly series, and reproduces these totals at base 18.
1950 →
76 years, hourly. The specialist competitor starts in 2000.
4
Calculation methods, because your contract decides, not us.
9 km
Grid, everywhere on land — no station required nearby.
any
Base temperature, fractional included, resolved at request time.
Why free degree-day data is usually unusable
The base
HDD18 is one building's answer
Pre-computing degree days at base 18 is the obvious shortcut, and it is what makes most free datasets commercially useless. A well-insulated office with internal gains balances nearer 15 °C; a draughty warehouse nearer 19. Handed an HDD18 series, both get a number that describes neither of them.
We store the hourly temperature instead, and do the integration when you ask. The base is a query parameter.
The averaging
A daily mean hides the day
A day that swung from 8 °C to 22 °C has a mean of 15 °C. Against a base of 18 that looks like a mild day with modest heating demand. In reality the building heated hard all night and needed nothing by afternoon.
Integrating hourly keeps that. It is a different number, and it is the right one — unless your contract says otherwise, in which case see below.
Four methods, because your contract decides
This is the detail that settles B2B deals. Our hourly integration is the most physically faithful — and useless to a customer whose contract is written on Costic, because their numbers will not match. So the method is a parameter.
| method= | HDD 18 °C | CDD 18 °C | When to use it |
|---|---|---|---|
hourly |
781.9 | 1331.6 | Default. Integrates the hourly deficit or excess — the most physically faithful. |
costic |
741.7 | 1349.5 | French DJU unifiés. Required by French energy-performance contracts. |
mean |
659.9 | 1267.8 | Daily mean against base. The most widespread international convention. |
eurostat |
587.7 | 656.6 | European statistics. Bases are fixed by the definition and ignore base. |
Same data, same base, same year, same place — and an 18 % spread between the top and the middle row. Anyone who hands you “the degree days” without saying which method has handed you a number you cannot reconcile. /v1/degree-days/compare-methods returns all four at once, so you can find the one that reproduces the figures already in your contract before you commit to a plan.
Four decisions that show up in your invoices
Calendar
Local days, not UTC days
A degree day is a property of a calendar day where the building is. Bucketing by UTC moves a slice of every night into the wrong day and quietly biases monthly totals. Every request takes the location's offset and groups accordingly; city endpoints know their own time zone.
Cities
The urban heat island, calibrated
Reanalysis under-reads built-up areas by 1–3 °C, which biases cooling degree days low — material if you are sizing air conditioning. City endpoints apply an offset measured against real station observations: Algiers +0.48 °C, Paris +1.13 °C.
Coordinate endpoints do not apply it, and say so.
Periods
Daily, weekly, monthly, yearly
All four on the same request, because contracts settle on different ones. Weeks are ISO weeks, so 1 January 2023 is reported in week 52 of 2022 — which is what your spreadsheet will do too. Every bucket carries its day count, so a partial month at the edge of a range is visible rather than silently short.
Quality
Coverage, and what is provisional
Every response carries a quality block: hours present, coverage below 1.0 when any are missing, and a count of provisional_days filled from forecast rather than final reanalysis — ERA5-Land publishes with about five days of latency. You can see exactly which part of a total is not yet final.
One request, ten years, one number
# Paris, UK base of 15.5 °C, ten years, monthly rows
curl -H "X-API-Key: $API_KEY" \
"https://api.climatememory.com/v1/degree-days\
?lat=48.86&lon=2.35&base=uk&breakdown=monthly\
&start=2015-01-01&end=2024-12-31"
# The same building, on the method its contract names
curl -H "X-API-Key: $API_KEY" \
"https://api.climatememory.com/v1/degree-days/city/fr/paris\
?base=18&method=costic&start=2024-01-01&end=2024-12-31"import httpx
# Weather-normalise a portfolio: same base, same method, many sites
def hdd(lat, lon, year, base=15.5, method="hourly"):
r = httpx.get(
"https://api.climatememory.com/v1/degree-days",
params={"lat": lat, "lon": lon, "base": base,
"method": method, "type": "HDD",
"start": f"{year}-01-01", "end": f"{year}-12-31"},
headers={"X-API-Key": API_KEY}, timeout=60,
)
r.raise_for_status()
return r.json()["totals"]["hdd"]
ratio = hdd(48.86, 2.35, 2024) / hdd(48.86, 2.35, 2023)
# consumption up 9 %, degree days up 11 % -> the building improved{
"location": { "latitude": 36.75, "longitude": 3.06,
"grid_cell": { "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 } ]
}# Add format=csv to any degree-days request. Paid plans only.
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
2024,3,131.77,9.62,31,14.05,1.0,false
# The file is named after the location and dates, so it is still
# identifiable six months later in a downloads folder.Who buys this, and what for
Energy performance contracts
Settle the year without arguing about the weather
A guaranteed-savings contract has to separate “the building got better” from “the winter was mild”. Degree days on the contract's own base and method are how that separation is written down — and method=costic is what a French contract will name.
Portfolio management
Compare 400 buildings in 12 countries
Each site gets its own local calendar, its own grid cell and, in cities, its own heat island correction — on one base and one method, so the comparison means something. No station coverage to check first.
HVAC sizing
Cooling load against a real cooling climate
CDD on the base the equipment actually balances at, in a city centre rather than at the airport where the reanalysis grid is coolest. 76 years of it, so a design year is chosen rather than assumed.
Software vendors
Ship degree days inside your own product
Commercial redistribution is permitted. Put the numbers in your energy-management platform, your billing engine or your ESG report; a line of attribution is the only obligation that follows you.
Where the numbers come from
ERA5-Land, the Copernicus reanalysis. A physical model run backwards over every observation ever assimilated, producing an hourly temperature field on a 9 km grid, everywhere on land, from 1950 to about five days ago.
Why that beats a station record for this job. A weather station carries every move, every instrument change and every gap in its history, so a thirty-year trend computed from one is partly a trend in the instrumentation. A reanalysis has none of that. It also has no coverage holes: a site 60 km from the nearest station is served exactly as well as one next door to an airport.
Where it is weaker. City centres, which reanalysis under-reads — hence the calibrated correction on city endpoints. And the last five days, which are provisional until the final reanalysis lands; the response counts those days for you.
The licence, which is the point. Copernicus publishes ERA5-Land under CC-BY-4.0: commercial use, redistribution and derived works all explicitly permitted. That is what makes this a product rather than a research download.
Common questions
What exactly is a degree day?
A measure of how far, and for how long, the outside temperature sat below or above a reference called the base. Heating degree days accumulate when it is colder than the base, cooling degree days when it is warmer.
They are the standard way to explain why a building consumed more energy this January than last without confusing weather with behaviour.
Can I use any base temperature?
Any value, fractions included. Named presets are accepted too: uk (15.5 °C), ashrae (18.333 °C, which is 65 °F), iso, france and eurostat (18 °C).
Different bases for heating and cooling are supported on the same request, because a building rarely balances at the same point in both directions.
Do you support DJU unifiés / Costic?
Yes — method=costic. It uses only the daily minimum and maximum with an empirical weighting for days that straddle the base, which is what French energy-performance contracts settle on.
Run /v1/degree-days/compare-methods against a period you already have figures for. If Costic reproduces them, use Costic. That check takes one request and prevents the argument.
How far back does the archive go?
1 January 1950 — 76 years, hourly, worldwide on land, on a 9 km grid. A single request may span up to 10 years; longer histories are several requests.
Do I need a weather station near the site?
No. Gridded reanalysis covers every land location, including sites with no station within 60 km. That is its main advantage over station-based degree-day providers, along with having no instrument changes or gaps in its history.
Can I export to CSV or Excel?
Add format=csv to any degree-days request on a paid plan. You get the breakdown rows — aggregated, never the hourly series — with the same maximum span as the JSON call, at four times the credits.
That bound 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 bound is what lets the format exist at all.
What does it cost?
Degree days are included from the Starter plan at €19 a month: 50,000 credits, weather included, CSV included. A degree-day request costs two credits for up to a year, plus one per additional year.
At 50,000 credits that is roughly 25,000 single-year lookups a month — enough for a portfolio of a few hundred buildings queried daily.
Can I resell the values inside my own product?
Yes. ERA5-Land is published under CC-BY-4.0, which permits commercial use, redistribution and derived works. Display an attribution line wherever the data appears — /v1/attribution returns the exact wording and needs no key.
Check it against figures you already have
Take a year you have signed-off numbers for, run compare-methods, and see which method reproduces them. That is the honest way to buy this.