# Degree Day API > Heating and cooling degree-day maths as an API, computed locally and deterministically. The daily endpoint computes the heating degree days, HDD = max(0, base − mean), and the cooling degree days, CDD = max(0, mean − base), for a single day from a base temperature and the daily mean — or the minimum and maximum, since the mean is taken as their average. The period endpoint sums the degree days over a list of daily temperatures (means or min/max pairs), returning the total HDD and CDD, the count of heating and cooling days and the average temperature — the standard way to characterise a heating or cooling season. The energy endpoint turns degree days into an energy estimate: the heat delivered is UA·DD·24/1000 kWh from the building heat-loss coefficient, the fuel or electricity input is that divided by the boiler efficiency (or a heat-pump COP), and — with an energy price — the cost. Everything is computed locally and deterministically, so it is instant and private. Ideal for building-energy, HVAC and facilities tools, heating-bill and fuel-budget estimation, weather-normalisation and energy-benchmarking apps, and engineering education. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is degree-day demand estimation; for U-value and heat-loss fabric calculations use a U-value API. ## Authentication All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys. ```bash curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/degreeday-api/..." ``` ## Pricing - **Free** (Free) — 2,000 calls/Mo, 2 req/s - **Starter** ($9/Mo) — 40,000 calls/Mo, 6 req/s - **Pro** ($24/Mo) — 250,000 calls/Mo, 18 req/s - **Mega** ($74/Mo) — 1,500,000 calls/Mo, 50 req/s ## Endpoints ### Degree Day #### `GET /v1/daily` — Daily degree days **Parameters:** - `base_temperature` (query, required, string) — Base temperature (°C) Example: `18` - `mean_temperature` (query, optional, string) — Daily mean temperature (°C) Example: `5` - `min_temperature` (query, optional, string) — Or daily minimum (°C) - `max_temperature` (query, optional, string) — and daily maximum (°C) **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/degreeday-api/v1/daily?base_temperature=18&mean_temperature=5" ``` **Response:** ```json { "data": { "mode": "heating", "note": "HDD = max(0, base − mean); CDD = max(0, mean − base). Mean = (min + max)/2 when not given.", "inputs": { "base_temperature": 18, "mean_temperature": 5 }, "cooling_degree_days": 0, "heating_degree_days": 13 }, "meta": { "timestamp": "2026-06-04T18:38:23.732Z", "request_id": "4cb40c86-639f-45ec-bcb2-63a536c76fe0" }, "status": "ok", "message": "Daily degree days", "success": true } ``` #### `GET /v1/energy` — Energy estimate **Parameters:** - `degree_days` (query, required, string) — Degree days (°C·day) Example: `21` - `heat_loss_coefficient` (query, required, string) — Heat-loss coefficient UA (W/K) Example: `200` - `efficiency` (query, optional, string) — Boiler efficiency or heat-pump COP (default 0.9) Example: `0.9` - `energy_price` (query, optional, string) — Price per kWh for the cost Example: `0.1` **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/degreeday-api/v1/energy?degree_days=21&heat_loss_coefficient=200&efficiency=0.9&energy_price=0.1" ``` **Response:** ```json { "data": { "note": "Delivered = UA·DD·24/1000 (kWh). Input = delivered/efficiency. Use efficiency > 1 for a heat-pump COP.", "inputs": { "efficiency": 0.9, "degree_days": 21, "heat_loss_coefficient": 200 }, "estimated_cost": 11.2, "input_energy_kwh": 112, "delivered_energy_kwh": 100.8 }, "meta": { "timestamp": "2026-06-04T18:38:23.836Z", "request_id": "a2e0f235-13bb-4765-88e4-34e5b0783f1c" }, "status": "ok", "message": "Energy estimate", "success": true } ``` #### `GET /v1/period` — Period degree days **Parameters:** - `base_temperature` (query, required, string) — Base temperature (°C) Example: `18` - `temperatures` (query, required, string) — JSON array of daily means or {min,max} Example: `[5,10,20,25]` **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/degreeday-api/v1/period?base_temperature=18&temperatures=%5B5%2C10%2C20%2C25%5D" ``` **Response:** ```json { "data": { "note": "Daily HDD/CDD summed over the period. Each entry is a mean temperature or a {min,max} pair.", "inputs": { "days": 4, "base_temperature": 18 }, "cooling_days": 2, "heating_days": 2, "average_temperature": 15, "cooling_degree_days": 9, "heating_degree_days": 21 }, "meta": { "timestamp": "2026-06-04T18:38:23.931Z", "request_id": "cfb9cbf3-89b3-464e-93b0-d777ba9762b3" }, "status": "ok", "message": "Period degree days", "success": true } ``` ### Meta #### `GET /v1/meta` — Spec **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/degreeday-api/v1/meta" ``` **Response:** ```json { "data": { "notes": "Temperatures in °C (base typically 15.5–18 °C), UA in W/K. Degree-days are a simple proxy for heating/cooling demand; mean = (min+max)/2 is the standard daily estimate.", "service": "degreeday-api", "formulae": { "cdd": "CDD = max(0, mean − base)", "hdd": "HDD = max(0, base − mean)", "energy": "delivered_kWh = UA·DD·24/1000, input = delivered/efficiency" }, "endpoints": { "GET /v1/meta": "This document.", "GET /v1/daily": "HDD and CDD for one day from a mean (or min+max) temperature against a base.", "GET /v1/energy": "Heating energy and cost from degree days and a heat-loss coefficient (UA).", "GET /v1/period": "Total HDD/CDD over a list of daily temperatures, with heating/cooling day counts." }, "description": "Heating and cooling degree-day calculator: daily and period HDD/CDD from temperatures, and an energy/cost estimate from a heat-loss coefficient." }, "meta": { "timestamp": "2026-06-04T18:38:24.017Z", "request_id": "3abad411-49eb-4c57-a763-7be555314194" }, "status": "ok", "message": "Meta", "success": true } ``` --- Marketplace page: https://www.oanor.com/api/degreeday-api OpenAPI spec: https://www.oanor.com/api/degreeday-api/openapi.json