{"openapi":"3.1.0","info":{"title":"Heat Pump COP API","version":"1.0.0","description":"Heat-pump and refrigeration performance maths as an API, computed locally and deterministically — the efficiency numbers an HVAC engineer, energy auditor or heat-pump installer actually works with. The cop endpoint gives the coefficient of performance and the US EER rating from the thermal capacity and the electrical power: a unit moving 7 kW of heat on 2 kW of electricity has a COP of 3.5 (an EER of 12), meaning 3.5 units of heating or cooling for every unit of electricity — which is why a heat pump beats resistance heating, where the COP is exactly 1. The carnot endpoint gives the unbeatable ideal limit set only by the absolute temperatures — heating = Th ÷ (Th − Tc), cooling = Tc ÷ (Th − Tc) in kelvin, where heating COP always equals cooling COP plus one — and, given a real COP, the second-law efficiency that says how close the machine runs to that ceiling; the smaller the temperature lift, the higher the limit, which is why ground-source and low-temperature systems beat air-source on a cold day. The capacity endpoint turns electrical power and a COP into the delivered heating or cooling in kilowatts, BTU per hour and tons of refrigeration — the extra energy over the electricity is pulled from the outside air, ground or water. Everything is computed locally and deterministically, so it is instant and private. Ideal for HVAC and refrigeration engineers, energy auditors, heat-pump and building-performance tools, and sustainability dashboards. Pure local computation — no key, no third-party service, instant. Estimates at the stated conditions — real COP falls as the temperature lift rises. 3 compute endpoints. For room sizing use an HVAC BTU API; for moist-air properties use a psychrometric API.","contact":{"name":"PremiumApi","url":"https://www.oanor.com/by/premiumapi"}},"servers":[{"url":"https://api.oanor.com/heatpump-api","description":"oanor gateway"}],"tags":[{"name":"Performance"},{"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/capacity":{"get":{"operationId":"get_v1_capacity","tags":["Performance"],"summary":"Delivered capacity from power and COP","description":"","parameters":[{"name":"power_input_kw","in":"query","required":true,"description":"Electrical power input (kW)","schema":{"type":"string"},"example":"2"},{"name":"cop","in":"query","required":true,"description":"Coefficient of performance","schema":{"type":"string"},"example":"3.5"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"Delivered heat (or cooling) = the electrical power × the COP. A 2 kW compressor at a COP of 3.5 moves 7 kW of heat — about 23,900 BTU/hr or 2 tons. The electricity is not 'lost': the extra energy is pulled from the outdoor air, ground or water, which is the whole point of a heat pump over a resistance heater.","inputs":{"cop":3.5,"power_input_kw":2},"capacity_kw":7,"capacity_tons":1.99,"capacity_btu_hr":23885},"meta":{"timestamp":"2026-06-06T23:53:55.458Z","request_id":"0b4a7625-793a-4872-81a6-5c8f591b991e"},"status":"ok","message":"Capacity","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/carnot":{"get":{"operationId":"get_v1_carnot","tags":["Performance"],"summary":"Ideal (Carnot) COP and second-law efficiency","description":"","parameters":[{"name":"hot_temp_c","in":"query","required":true,"description":"Warm-side temperature (°C)","schema":{"type":"string"},"example":"20"},{"name":"cold_temp_c","in":"query","required":true,"description":"Cold-side temperature (°C)","schema":{"type":"string"},"example":"0"},{"name":"mode","in":"query","required":false,"description":"heating or cooling (default heating)","schema":{"type":"string"},"example":"heating"},{"name":"actual_cop","in":"query","required":false,"description":"Real COP to grade against the limit","schema":{"type":"string"}}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"The Carnot COP is the unbeatable ceiling set only by the absolute temperatures: heating = Th ÷ (Th − Tc), cooling = Tc ÷ (Th − Tc), with T in kelvin (and heating COP always equals cooling COP + 1). The smaller the temperature lift, the higher the ceiling — which is why ground-source and low-temperature underfloor systems outperform air-source on a cold day.","inputs":{"mode":"heating","hot_temp_c":20,"cold_temp_c":0},"carnot_cop":14.66,"carnot_cop_cooling":13.66,"carnot_cop_heating":14.66,"temperature_lift_c":20},"meta":{"timestamp":"2026-06-06T23:53:55.554Z","request_id":"399e0579-da6a-43dd-ab48-b96ac3e5aef7"},"status":"ok","message":"Carnot COP","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/cop":{"get":{"operationId":"get_v1_cop","tags":["Performance"],"summary":"COP and EER from capacity and power","description":"","parameters":[{"name":"capacity_kw","in":"query","required":true,"description":"Thermal capacity, heating or cooling (kW)","schema":{"type":"string"},"example":"7.034"},{"name":"power_input_kw","in":"query","required":true,"description":"Electrical power input (kW)","schema":{"type":"string"},"example":"2"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"cop":3.52,"note":"COP = the heat moved ÷ the electrical power, in the same units — a COP of 3.5 means 3.5 kW of heating or cooling for every 1 kW of electricity, which is why heat pumps beat resistance heating (COP = 1). EER is the same thing in Btu per watt-hour (COP × 3.412), the US cooling rating. Both fall as the temperature lift grows, so a quoted COP only holds at its rating conditions.","inputs":{"capacity_kw":7.034,"power_input_kw":2},"capacity_tons":2,"eer_btu_per_wh":12,"capacity_btu_hr":24001},"meta":{"timestamp":"2026-06-06T23:53:55.638Z","request_id":"e3687876-2cd4-45d5-a72b-64680c6a6e91"},"status":"ok","message":"COP / EER","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":"kW (power/thermal), °C, plus BTU/hr and tons. COP = capacity ÷ power; EER = COP × 3.412; Carnot heating = Th/(Th−Tc), cooling = Tc/(Th−Tc) (kelvin). Estimates at the stated conditions. For room sizing use an HVAC API; for moist air a psychrometric API.","service":"heatpump-api","endpoints":{"GET /v1/cop":"COP and EER from the thermal capacity and electrical power.","GET /v1/meta":"This document.","GET /v1/carnot":"Ideal (Carnot) COP from the source/sink temperatures, with second-law efficiency.","GET /v1/capacity":"Delivered thermal capacity from power and COP."},"description":"Heat-pump / refrigeration performance maths: COP and EER from capacity and power, the Carnot limit from temperatures, and the delivered capacity from power and COP."},"meta":{"timestamp":"2026-06-06T23:53:55.729Z","request_id":"0d722c74-6575-4a46-b787-1c6b9c40b9bf"},"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":5900,"rps_limit":2,"hard_limit":true},{"slug":"starter","name":"Starter","price_cents_month":1180,"monthly_call_quota":66000,"rps_limit":6,"hard_limit":true},{"slug":"pro","name":"Pro","price_cents_month":3650,"monthly_call_quota":272000,"rps_limit":15,"hard_limit":true},{"slug":"mega","name":"Mega","price_cents_month":11200,"monthly_call_quota":1340000,"rps_limit":40,"hard_limit":true}],"x-oanor-marketplace-url":"https://www.oanor.com/api/heatpump-api"}