{"openapi":"3.1.0","info":{"title":"Water Hammer API","version":"1.0.0","description":"Water-hammer (hydraulic-transient) maths as an API, computed locally and deterministically — the surge-pressure, wave-speed and valve-timing numbers a piping or plumbing engineer guards a system with. The surge endpoint applies the Joukowsky equation Δp = ρ · a · Δv: a sudden stop of the flow spikes the pressure by the fluid density × the pressure-wave speed × the velocity change — stopping 2 m/s of water at a ≈ 1200 m/s adds about 24 bar (348 psi), far above the line pressure, which is what bangs the pipes and can split fittings. The wave-speed endpoint gives that pressure-wave speed: a = √(K/ρ) in a rigid pipe (≈ 1,480 m/s for water), slowed in a real elastic pipe to √(K/ρ) ÷ √(1 + (K·D)/(E·t)) — a thin or plastic pipe gives a lower wave speed and a gentler surge, which is why PVC tolerates hammer better than steel. The critical-time endpoint gives 2L/a, the round-trip time of the wave: close a valve faster than this and you get the full Joukowsky surge, slower and the returning relief wave eats into it, so sizing closure times (or fitting a surge tank or air chamber) above the critical time is the standard cure. Everything is computed locally and deterministically, so it is instant and private. Ideal for piping- and plumbing-design tools, pump-station and pipeline-surge analysis, and hydraulic-engineering utilities. Pure local computation — no key, no third-party service, instant. Idealised single-pipe transient. 3 compute endpoints. For steady pipe pressure drop use a Darcy API; for pump head and affinity a pump API.","contact":{"name":"PremiumApi","url":"https://www.oanor.com/by/premiumapi"}},"servers":[{"url":"https://api.oanor.com/waterhammer-api","description":"oanor gateway"}],"tags":[{"name":"Hammer"},{"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/critical-time":{"get":{"operationId":"get_v1_critical_time","tags":["Hammer"],"summary":"Critical valve-closure time","description":"","parameters":[{"name":"pipe_length_m","in":"query","required":true,"description":"Pipe length (m)","schema":{"type":"string"},"example":"500"},{"name":"wave_speed_m_s","in":"query","required":true,"description":"Pressure-wave speed (m/s)","schema":{"type":"string"},"example":"1200"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"The critical time = 2L/a, the round-trip time for the pressure wave to travel to the far end of the pipe and back. Close the valve faster than this and you get the full Joukowsky surge; close it slower and the returning relief wave eats into the rise, so the surge falls roughly in proportion. Sizing valve-closure times (or fitting a surge tank/air chamber) above the critical time is the standard way to tame water hammer.","inputs":{"pipe_length_m":500,"wave_speed_m_s":1200},"critical_time_s":0.8333},"meta":{"timestamp":"2026-06-07T08:18:01.688Z","request_id":"f4d0e2e5-05dd-4dde-8afa-dcbd78865f70"},"status":"ok","message":"Critical 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/surge":{"get":{"operationId":"get_v1_surge","tags":["Hammer"],"summary":"Joukowsky surge pressure","description":"","parameters":[{"name":"wave_speed_m_s","in":"query","required":true,"description":"Pressure-wave speed (m/s)","schema":{"type":"string"},"example":"1200"},{"name":"velocity_change_m_s","in":"query","required":true,"description":"Velocity change (m/s)","schema":{"type":"string"},"example":"2"},{"name":"fluid_density_kg_m3","in":"query","required":false,"description":"Fluid density (kg/m³, default 998)","schema":{"type":"string"},"example":"998"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"The Joukowsky equation: a sudden stop of the flow spikes the pressure by Δp = ρ · a · Δv, where a is the pressure-wave speed — stopping 2 m/s of water (a≈1200 m/s) adds about 24 bar, far above the line pressure, which is what bangs the pipes and can split fittings. This is the worst case for an instantaneous closure; a slower valve (longer than the critical time) caps the surge well below it.","inputs":{"wave_speed_m_s":1200,"fluid_density_kg_m3":998,"velocity_change_m_s":2},"surge_head_m":244.73,"surge_pressure_pa":2395200,"surge_pressure_bar":23.952,"surge_pressure_psi":347.39},"meta":{"timestamp":"2026-06-07T08:18:01.770Z","request_id":"7c54a78d-3fc2-4775-ba18-3c927e466629"},"status":"ok","message":"Surge pressure","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/wave-speed":{"get":{"operationId":"get_v1_wave_speed","tags":["Hammer"],"summary":"Pressure-wave speed in a pipe","description":"","parameters":[{"name":"fluid_density_kg_m3","in":"query","required":false,"description":"Fluid density (kg/m³, default 998)","schema":{"type":"string"},"example":"998"},{"name":"bulk_modulus_gpa","in":"query","required":false,"description":"Fluid bulk modulus (GPa, default 2.2)","schema":{"type":"string"},"example":"2.2"},{"name":"pipe_youngs_gpa","in":"query","required":false,"description":"Pipe Young's modulus (GPa)","schema":{"type":"string"},"example":"200"},{"name":"pipe_diameter_mm","in":"query","required":false,"description":"Pipe inside diameter (mm)","schema":{"type":"string"},"example":"100"},{"name":"wall_thickness_mm","in":"query","required":false,"description":"Pipe wall thickness (mm)","schema":{"type":"string"},"example":"5"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"The pressure wave travels at a = √(K/ρ) in a perfectly rigid pipe (≈1,480 m/s for water), but a real elastic pipe slows it: a = √(K/ρ) ÷ √(1 + (K·D)/(E·t)), where K is the fluid bulk modulus, E the pipe's elastic modulus and D/t the diameter-to-wall ratio. A thin or flexible (plastic) pipe gives a much lower wave speed and so a gentler surge — one reason PVC tolerates hammer better than steel.","inputs":{"pipe_youngs_gpa":200,"bulk_modulus_gpa":2.2,"pipe_diameter_mm":100,"wall_thickness_mm":5,"fluid_density_kg_m3":998},"wave_speed_m_s":1344.2,"rigid_pipe_wave_speed_m_s":1484.7},"meta":{"timestamp":"2026-06-07T08:18:01.863Z","request_id":"299f0594-2507-4e46-a5b1-a085c555bffa"},"status":"ok","message":"Wave speed","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":"SI (kg/m³, m/s, Pa/bar, m). Δp = ρ·a·Δv; a = √(K/ρ)/√(1+(K·D)/(E·t)); critical time = 2L/a. Water: ρ≈998, K≈2.2 GPa. For steady pipe pressure drop use a Darcy API; for pump head a pump API.","service":"waterhammer-api","endpoints":{"GET /v1/meta":"This document.","GET /v1/surge":"Joukowsky surge pressure (Δp = ρ·a·Δv).","GET /v1/wave-speed":"Pressure-wave speed in a rigid or elastic pipe.","GET /v1/critical-time":"Critical valve-closure time (2L/a)."},"description":"Water-hammer (hydraulic transient) maths: Joukowsky surge pressure, pipe wave speed, and critical valve-closure time."},"meta":{"timestamp":"2026-06-07T08:18:01.948Z","request_id":"f799f711-2963-4b8b-b55b-b5bb676f7378"},"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":4900,"rps_limit":2,"hard_limit":true},{"slug":"starter","name":"Starter","price_cents_month":1260,"monthly_call_quota":50500,"rps_limit":6,"hard_limit":true},{"slug":"pro","name":"Pro","price_cents_month":3900,"monthly_call_quota":216000,"rps_limit":15,"hard_limit":true},{"slug":"mega","name":"Mega","price_cents_month":12050,"monthly_call_quota":1125000,"rps_limit":40,"hard_limit":true}],"x-oanor-marketplace-url":"https://www.oanor.com/api/waterhammer-api"}