{"openapi":"3.1.0","info":{"title":"Pool Heating API","version":"1.0.0","description":"Swimming-pool and spa heating maths as an API, computed locally and deterministically — the thermodynamics a pool owner, builder or service tech sizes a heater and budgets a heat-up with. The heat-time endpoint gives the hours to warm a body of water: energy = gallons × 8.34 lb/gal × the temperature rise in °F (that many BTU), divided by the heater's BTU/hr output — raising 20,000 gallons by 10 °F is 1,668,000 BTU, about 4.2 hours on a 400,000 BTU/hr gas heater before surface losses. The heater-size endpoint inverts it: the output you need to hit a temperature rise within a target time, so the same job in 24 hours wants only about 69,500 BTU/hr. The heat-pump endpoint gives a heat pump's electricity and cost — kWh = thermal BTU ÷ 3412 ÷ the COP (5–6 for pool units in mild weather) — so that 1,668,000 BTU costs about 89 kWh at a COP of 5.5, a fraction of resistance heat. Pass the temperature rise directly, or a current and target temperature. Everything is computed locally and deterministically, so it is instant and private. Ideal for pool-builder and service apps, heater-sizing and quote tools, spa and hot-tub calculators, and energy-comparison sites. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 compute endpoints. Ideal figures — add for surface and wind losses. For pool chemistry use a pool-chemistry API.","contact":{"name":"PremiumApi","url":"https://www.oanor.com/by/premiumapi"}},"servers":[{"url":"https://api.oanor.com/poolheat-api","description":"oanor gateway"}],"tags":[{"name":"Pool Heating"},{"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/heat-pump":{"get":{"operationId":"get_v1_heat_pump","tags":["Pool Heating"],"summary":"Heat-pump electricity and cost","description":"","parameters":[{"name":"volume_gallons","in":"query","required":true,"description":"Water volume in US gallons","schema":{"type":"string"},"example":"20000"},{"name":"temp_rise_f","in":"query","required":false,"description":"Temperature rise in °F","schema":{"type":"string"},"example":"10"},{"name":"cop","in":"query","required":false,"description":"Coefficient of performance (default 5.5)","schema":{"type":"string"},"example":"5.5"},{"name":"price_per_kwh","in":"query","required":false,"description":"Electricity price per kWh","schema":{"type":"string"},"example":"0.15"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"cost":13.33,"note":"A heat-pump heater moves more heat than it consumes: electricity = thermal BTU ÷ 3412 ÷ the COP (typically 5–6 for pool units in mild weather, less in the cold). It is far cheaper to run than gas or resistance heat but heats slowly, so it suits holding temperature, not a fast warm-up.","inputs":{"cop":5.5,"temp_rise_f":10,"volume_gallons":20000},"total_btu":1668000,"electricity_kwh":88.88},"meta":{"timestamp":"2026-06-06T15:30:43.771Z","request_id":"75752aa7-ca79-485a-87d5-a69611dc2174"},"status":"ok","message":"Heat pump","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/heat-time":{"get":{"operationId":"get_v1_heat_time","tags":["Pool Heating"],"summary":"Hours to heat by a temperature rise","description":"","parameters":[{"name":"volume_gallons","in":"query","required":true,"description":"Water volume in US gallons","schema":{"type":"string"},"example":"20000"},{"name":"temp_rise_f","in":"query","required":false,"description":"Temperature rise in °F (or use current/target)","schema":{"type":"string"},"example":"10"},{"name":"current_temp_f","in":"query","required":false,"description":"Current temperature °F","schema":{"type":"string"},"example":"70"},{"name":"target_temp_f","in":"query","required":false,"description":"Target temperature °F","schema":{"type":"string"},"example":"80"},{"name":"heater_btu_per_hr","in":"query","required":true,"description":"Heater output in BTU/hr","schema":{"type":"string"},"example":"400000"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"Energy to heat water = gallons × 8.34 lb/gal × the temperature rise in °F (that many BTU). Divide by the heater's BTU/hr output for the run-time. This is the ideal — real pools also lose heat from the surface as they warm, so allow extra, especially in wind or uncovered.","hours":4.17,"inputs":{"temp_rise_f":10,"volume_gallons":20000,"heater_btu_per_hr":400000},"minutes":250,"total_btu":1668000},"meta":{"timestamp":"2026-06-06T15:30:43.863Z","request_id":"b490fb06-fb79-409a-a11b-dbc517a60f4a"},"status":"ok","message":"Heat time","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/heater-size":{"get":{"operationId":"get_v1_heater_size","tags":["Pool Heating"],"summary":"Heater output to heat in time","description":"","parameters":[{"name":"volume_gallons","in":"query","required":true,"description":"Water volume in US gallons","schema":{"type":"string"},"example":"20000"},{"name":"temp_rise_f","in":"query","required":false,"description":"Temperature rise in °F","schema":{"type":"string"},"example":"10"},{"name":"current_temp_f","in":"query","required":false,"description":"Current temperature °F","schema":{"type":"string"}},{"name":"target_temp_f","in":"query","required":false,"description":"Target temperature °F","schema":{"type":"string"}},{"name":"target_hours","in":"query","required":true,"description":"Hours to heat within","schema":{"type":"string"},"example":"24"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"Required output = total BTU ÷ the hours you want it heated in. Pool gas heaters are commonly 100k–400k BTU/hr; size up for surface and wind losses and a sensible heat-up time. A bigger heater costs more up front but reaches temperature faster and idles less.","inputs":{"temp_rise_f":10,"target_hours":24,"volume_gallons":20000},"total_btu":1668000,"required_btu_per_hr":69500},"meta":{"timestamp":"2026-06-06T15:30:43.961Z","request_id":"4cd63db7-3d0a-449a-ab40-cf0e6aab121d"},"status":"ok","message":"Heater size","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":"BTU = gallons × 8.34 × °F rise; ÷ heater BTU/hr for time; heat pump kWh = BTU ÷ 3412 ÷ COP. Pass temp_rise_f, or current_temp_f + target_temp_f. Ideal figures — add for surface/wind losses. For pool chemistry use a pool-chemistry API.","service":"poolheat-api","endpoints":{"GET /v1/meta":"This document.","GET /v1/heat-pump":"A heat pump's electricity (kWh) and optional cost for the heat.","GET /v1/heat-time":"Hours to raise a volume by a temperature rise at a heater's BTU/hr.","GET /v1/heater-size":"Heater output (BTU/hr) needed to heat within a target time."},"description":"Pool & spa heating maths: time to heat by a temperature rise, the heater size to do it in time, and a heat pump's electricity and cost."},"meta":{"timestamp":"2026-06-06T15:30:44.040Z","request_id":"478752c0-5032-4e8a-a7cb-13ff21baa59e"},"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":420,"rps_limit":2,"hard_limit":true},{"slug":"starter","name":"Starter","price_cents_month":560,"monthly_call_quota":11500,"rps_limit":6,"hard_limit":true},{"slug":"pro","name":"Pro","price_cents_month":1780,"monthly_call_quota":76000,"rps_limit":15,"hard_limit":true},{"slug":"mega","name":"Mega","price_cents_month":5280,"monthly_call_quota":250000,"rps_limit":36,"hard_limit":true}],"x-oanor-marketplace-url":"https://www.oanor.com/api/poolheat-api"}