{"openapi":"3.1.0","info":{"title":"Rainwater Harvesting API","version":"1.0.0","description":"Rainwater-harvesting maths as an API, computed locally and deterministically. The harvest endpoint works out how much water a roof collects from a given rainfall — from the catchment (roof plan) area, the rainfall depth and a runoff coefficient it returns the harvested volume in litres, US and UK gallons and cubic metres, using the identity that 1 mm of rain over 1 m² collects 1 litre before losses. The runoff coefficient can be given directly or looked up from the roof type (smooth metal collects the most at ~0.9, green roofs the least at ~0.3). The demand endpoint sizes a storage tank from a daily demand (given directly or as people × litres per person) and the length of the dry spell you want to cover, and — if you also pass the annual rainfall and roof area — checks whether a year of harvest can meet a year of demand. The firstflush endpoint sizes a first-flush diverter, the volume of dirty initial rain to discard. Areas accept square metres or square feet (or length × width), rainfall accepts millimetres, centimetres or inches. Everything is computed locally and deterministically, so it is instant and private. Ideal for sustainability and off-grid apps, plumbing and landscaping tools, smart-home water systems, and construction planners. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 4 endpoints. This is rainwater catchment maths; for roof pitch and area geometry use a roofing API and for general construction material quantities use a construction API.","contact":{"name":"PremiumApi","url":"https://www.oanor.com/by/premiumapi"}},"servers":[{"url":"https://api.oanor.com/rainwater-api","description":"oanor gateway"}],"tags":[{"name":"Rainwater"},{"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/demand":{"get":{"operationId":"get_v1_demand","tags":["Rainwater"],"summary":"Storage tank sizing","description":"","parameters":[{"name":"daily_demand_litres","in":"query","required":false,"description":"Daily demand (or people)","schema":{"type":"string"},"example":"150"},{"name":"people","in":"query","required":false,"description":"People in household","schema":{"type":"string"}},{"name":"litres_per_person","in":"query","required":false,"description":"Per-person l/day (default 150)","schema":{"type":"string"}},{"name":"dry_days","in":"query","required":true,"description":"Dry spell to cover (days)","schema":{"type":"string"},"example":"30"},{"name":"annual_rainfall_mm","in":"query","required":false,"description":"For yearly supply check","schema":{"type":"string"}},{"name":"area","in":"query","required":false,"description":"Roof area (for supply check)","schema":{"type":"string"}},{"name":"roof_type","in":"query","required":false,"description":"Roof type (for supply check)","schema":{"type":"string"}}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"Required storage = daily demand × dry days. Supply check (if annual_rainfall_mm + area given) compares yearly harvest to yearly demand.","dry_days":30,"required_storage":{"litres":4500,"uk_gallons":989.9,"us_gallons":1188.8,"cubic_metres":4.5},"daily_demand_litres":150},"meta":{"timestamp":"2026-06-04T01:59:11.949Z","request_id":"4115c221-92e3-4288-8921-0810e482d07a"},"status":"ok","message":"Storage tank sizing from demand and a dry spell","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/firstflush":{"get":{"operationId":"get_v1_firstflush","tags":["Rainwater"],"summary":"First-flush diverter volume","description":"","parameters":[{"name":"area","in":"query","required":false,"description":"Catchment area (or length+width)","schema":{"type":"string"},"example":"80"},{"name":"length","in":"query","required":false,"description":"Roof length","schema":{"type":"string"}},{"name":"width","in":"query","required":false,"description":"Roof width","schema":{"type":"string"}},{"name":"area_unit","in":"query","required":false,"description":"m2|ft2","schema":{"type":"string"},"example":"m2"},{"name":"flush_mm","in":"query","required":false,"description":"Discard depth (default 0.5 mm)","schema":{"type":"string"},"example":"0.5"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"First-flush diverter discards the dirty first ~0.5–2 mm of rain. Volume = area(m²) × flush(mm).","flush_mm":0.5,"diverter_volume":{"litres":40,"uk_gallons":8.8,"us_gallons":10.6,"cubic_metres":0.04},"catchment_area_m2":80},"meta":{"timestamp":"2026-06-04T01:59:12.018Z","request_id":"a2d3cea7-ef25-4d88-b0b2-afff2006122d"},"status":"ok","message":"First-flush diverter volume","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/harvest":{"get":{"operationId":"get_v1_harvest","tags":["Rainwater"],"summary":"Collected volume from roof + rainfall","description":"","parameters":[{"name":"area","in":"query","required":false,"description":"Catchment area (or length+width)","schema":{"type":"string"},"example":"100"},{"name":"length","in":"query","required":false,"description":"Roof length","schema":{"type":"string"}},{"name":"width","in":"query","required":false,"description":"Roof width","schema":{"type":"string"}},{"name":"area_unit","in":"query","required":false,"description":"m2|ft2 (or m|ft for L×W)","schema":{"type":"string"},"example":"m2"},{"name":"rainfall","in":"query","required":true,"description":"Rainfall depth","schema":{"type":"string"},"example":"25"},{"name":"rainfall_unit","in":"query","required":false,"description":"mm|cm|in","schema":{"type":"string"},"example":"mm"},{"name":"roof_type","in":"query","required":false,"description":"metal|concrete|clay_tile|asphalt_shingle|green_roof|…","schema":{"type":"string"},"example":"metal"},{"name":"runoff_coefficient","in":"query","required":false,"description":"Or explicit 0-1","schema":{"type":"string"}}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"Collected ≈ area(m²) × rainfall(mm) × runoff coefficient. 1 mm over 1 m² = 1 litre before losses.","collected":{"litres":2250,"uk_gallons":494.9,"us_gallons":594.4,"cubic_metres":2.25},"rainfall_mm":25,"catchment_area_m2":100,"coefficient_source":"metal","runoff_coefficient":0.9},"meta":{"timestamp":"2026-06-04T01:59:12.109Z","request_id":"8d78cd32-d94c-4be5-b5bd-468b2b935bc2"},"status":"ok","message":"Collected volume from roof area and rainfall","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/rooftypes":{"get":{"operationId":"get_v1_rooftypes","tags":["Rainwater"],"summary":"Runoff coefficient reference","description":"","parameters":[],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"Runoff (collection) coefficients are typical values; smooth metal roofs collect the most, green roofs the least.","roof_types":{"metal":0.9,"gravel":0.7,"concrete":0.8,"clay_tile":0.8,"green_roof":0.3,"glazed_tile":0.85,"concrete_tile":0.8,"asphalt_shingle":0.85},"default_coefficient":0.85},"meta":{"timestamp":"2026-06-04T01:59:12.201Z","request_id":"eaa13d47-233c-440b-a26e-4b2ed57b92f2"},"status":"ok","message":"Runoff coefficient reference","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":{"api":"rainwater","note":"Rainwater harvesting maths — computed locally and deterministically, no key, no third-party service.","constants":{"MM_PER_IN":25.4,"M2_PER_FT2":0.09290304,"L_PER_UKGAL":4.54609,"L_PER_USGAL":3.785411784},"endpoints":["/v1/harvest","/v1/demand","/v1/firstflush","/v1/rooftypes","/v1/meta"]},"meta":{"timestamp":"2026-06-04T01:59:12.271Z","request_id":"11557ca3-8264-4bda-b6a0-96fd753d7585"},"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":12835,"rps_limit":2,"hard_limit":true},{"slug":"starter","name":"Starter","price_cents_month":1435,"monthly_call_quota":22450,"rps_limit":8,"hard_limit":true},{"slug":"pro","name":"Pro","price_cents_month":3425,"monthly_call_quota":274500,"rps_limit":20,"hard_limit":true},{"slug":"mega","name":"Mega","price_cents_month":7225,"monthly_call_quota":1415000,"rps_limit":50,"hard_limit":true}],"x-oanor-marketplace-url":"https://www.oanor.com/api/rainwater-api"}