{"openapi":"3.1.0","info":{"title":"Water Turnover API","version":"1.0.0","description":"Water turnover and circulation maths as an API, computed locally and deterministically — the flow-rate numbers a pool tech or aquarist sizes a pump to. The turnover endpoint relates a body of water's volume to its flow: turnover time = volume ÷ flow rate, and turnovers per day = 24 ÷ turnover time, so a 50,000-litre pool circulated at 10,000 L/h turns over in 5 hours, almost 5 times a day (pools usually target an 8–12 hour turnover, 2–4 a day); give a target turnover time instead and it returns the flow rate to size the pump to. The aquarium endpoint accounts for the real-world head loss that robs a pump of flow: effective flow = rated flow × (1 − head loss), so a 1,500 L/h pump at 40 % loss really moves 900 L/h, about 4.5× a 200-litre tank an hour; give a target turnovers-per-hour (freshwater 4–6×, planted 5–10×, reef 10×+) and it returns the rated pump to buy so losses still leave enough flow. Everything is computed locally and deterministically, so it is instant and private. Ideal for pool-service, aquarium, hydroponics, water-feature and pond app developers, pump-sizing and circulation tools, and equipment education. Pure local computation — no key, no third-party service, instant. Use consistent volume and flow units. Live, nothing stored. 2 compute endpoints. For pump power and head use a pump API; for pool chemistry a pool-chemistry API.","contact":{"name":"PremiumApi","url":"https://www.oanor.com/by/premiumapi"}},"servers":[{"url":"https://api.oanor.com/turnover-api","description":"oanor gateway"}],"tags":[{"name":"Turnover"},{"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/aquarium":{"get":{"operationId":"get_v1_aquarium","tags":["Turnover"],"summary":"Filtration with head loss","description":"","parameters":[{"name":"tank_volume","in":"query","required":true,"description":"Tank volume","schema":{"type":"string"},"example":"200"},{"name":"pump_flow","in":"query","required":false,"description":"Rated pump flow/hr (for effective)","schema":{"type":"string"},"example":"1500"},{"name":"target_turnovers_per_hour","in":"query","required":false,"description":"Or target ×/hr (for rated pump)","schema":{"type":"string"}},{"name":"head_loss_percent","in":"query","required":false,"description":"Head loss % (default 40)","schema":{"type":"string"}}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"Effective flow = rated pump flow × (1 − head loss). Turnovers/hour = effective ÷ tank. Freshwater wants ~4–6×/hr, planted ~5–10×, reef ~10×+.","inputs":{"pump_flow":1500,"tank_volume":200,"head_loss_percent":40},"turnovers_per_hour":4.5,"effective_flow_rate":900},"meta":{"timestamp":"2026-06-06T07:14:10.379Z","request_id":"36a2b1ff-d7c5-471a-af91-7e75a7f63553"},"status":"ok","message":"Aquarium filtration","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/turnover":{"get":{"operationId":"get_v1_turnover","tags":["Turnover"],"summary":"Turnover time / required flow","description":"","parameters":[{"name":"volume","in":"query","required":true,"description":"Water volume","schema":{"type":"string"},"example":"50000"},{"name":"flow_rate","in":"query","required":false,"description":"Flow per hour (for turnover time)","schema":{"type":"string"},"example":"10000"},{"name":"target_turnover_hours","in":"query","required":false,"description":"Or target turnover hours (for flow)","schema":{"type":"string"}}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"Turnover time = volume ÷ flow rate (per hour). Turnovers/day = 24 ÷ turnover time. Swimming pools usually target 2–4 turnovers a day (an 8–12 h turnover).","inputs":{"volume":50000,"flow_rate":10000},"turnovers_per_day":4.8,"turnover_time_hours":5,"turnover_time_minutes":300},"meta":{"timestamp":"2026-06-06T07:14:10.471Z","request_id":"29e11d51-7137-4c8e-8991-a186b17631ae"},"status":"ok","message":"Turnover 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/meta":{"get":{"operationId":"get_v1_meta","tags":["Meta"],"summary":"Spec","description":"","parameters":[],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"notes":"Use consistent volume and flow units (litres + litres/hour, or gallons + GPH). Pools target an 8–12 h turnover (2–4/day); aquariums 4–10× the tank per hour. For pump power use a pump API.","service":"turnover-api","endpoints":{"GET /v1/meta":"This document.","GET /v1/aquarium":"Effective turnover after head loss, or the rated pump for a target turnovers-per-hour.","GET /v1/turnover":"Turnover time and turnovers/day from volume + flow, or the flow for a target turnover."},"description":"Water turnover & circulation maths: pool/tank turnover time, turnovers per day, and aquarium filtration with head loss."},"meta":{"timestamp":"2026-06-06T07:14:10.557Z","request_id":"93ec1645-f823-403e-98a0-d755fc5c61cf"},"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":5350,"rps_limit":2,"hard_limit":true},{"slug":"starter","name":"Starter","price_cents_month":425,"monthly_call_quota":53500,"rps_limit":6,"hard_limit":true},{"slug":"pro","name":"Pro","price_cents_month":1175,"monthly_call_quota":247000,"rps_limit":15,"hard_limit":true},{"slug":"mega","name":"Mega","price_cents_month":3700,"monthly_call_quota":1410000,"rps_limit":40,"hard_limit":true}],"x-oanor-marketplace-url":"https://www.oanor.com/api/turnover-api"}