{"openapi":"3.1.0","info":{"title":"Degree Day API","version":"1.0.0","description":"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.","contact":{"name":"PremiumApi","url":"https://www.oanor.com/by/premiumapi"}},"servers":[{"url":"https://api.oanor.com/degreeday-api","description":"oanor gateway"}],"tags":[{"name":"Degree Day"},{"name":"Meta"}],"components":{"securitySchemes":{"oanorKey":{"type":"apiKey","in":"header","name":"x-oanor-key","description":"Get your key at https://www.oanor.com/developer/keys"}}},"security":[{"oanorKey":[]}],"paths":{"/v1/daily":{"get":{"operationId":"get_v1_daily","tags":["Degree Day"],"summary":"Daily degree days","description":"","parameters":[{"name":"base_temperature","in":"query","required":true,"description":"Base temperature (°C)","schema":{"type":"string"},"example":"18"},{"name":"mean_temperature","in":"query","required":false,"description":"Daily mean temperature (°C)","schema":{"type":"string"},"example":"5"},{"name":"min_temperature","in":"query","required":false,"description":"Or daily minimum (°C)","schema":{"type":"string"}},{"name":"max_temperature","in":"query","required":false,"description":"and daily maximum (°C)","schema":{"type":"string"}}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/energy":{"get":{"operationId":"get_v1_energy","tags":["Degree Day"],"summary":"Energy estimate","description":"","parameters":[{"name":"degree_days","in":"query","required":true,"description":"Degree days (°C·day)","schema":{"type":"string"},"example":"21"},{"name":"heat_loss_coefficient","in":"query","required":true,"description":"Heat-loss coefficient UA (W/K)","schema":{"type":"string"},"example":"200"},{"name":"efficiency","in":"query","required":false,"description":"Boiler efficiency or heat-pump COP (default 0.9)","schema":{"type":"string"},"example":"0.9"},{"name":"energy_price","in":"query","required":false,"description":"Price per kWh for the cost","schema":{"type":"string"},"example":"0.1"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/period":{"get":{"operationId":"get_v1_period","tags":["Degree Day"],"summary":"Period degree days","description":"","parameters":[{"name":"base_temperature","in":"query","required":true,"description":"Base temperature (°C)","schema":{"type":"string"},"example":"18"},{"name":"temperatures","in":"query","required":true,"description":"JSON array of daily means or {min,max}","schema":{"type":"string"},"example":"[5,10,20,25]"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/meta":{"get":{"operationId":"get_v1_meta","tags":["Meta"],"summary":"Spec","description":"","parameters":[],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}}},"x-oanor-pricing":[{"slug":"free","name":"Free","price_cents_month":0,"monthly_call_quota":2000,"rps_limit":2,"hard_limit":true},{"slug":"starter","name":"Starter","price_cents_month":900,"monthly_call_quota":40000,"rps_limit":6,"hard_limit":true},{"slug":"pro","name":"Pro","price_cents_month":2400,"monthly_call_quota":250000,"rps_limit":18,"hard_limit":true},{"slug":"mega","name":"Mega","price_cents_month":7400,"monthly_call_quota":1500000,"rps_limit":50,"hard_limit":true}],"x-oanor-marketplace-url":"https://www.oanor.com/api/degreeday-api"}