# Water Hammer API
> 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.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/waterhammer-api/..."
```

## Pricing
- **Free** (Free) — 4,900 calls/Mo, 2 req/s
- **Starter** ($13/Mo) — 50,500 calls/Mo, 6 req/s
- **Pro** ($39/Mo) — 216,000 calls/Mo, 15 req/s
- **Mega** ($121/Mo) — 1,125,000 calls/Mo, 40 req/s

## Endpoints

### Hammer

#### `GET /v1/critical-time` — Critical valve-closure time

**Parameters:**
- `pipe_length_m` (query, required, string) — Pipe length (m) Example: `500`
- `wave_speed_m_s` (query, required, string) — Pressure-wave speed (m/s) Example: `1200`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/waterhammer-api/v1/critical-time?pipe_length_m=500&wave_speed_m_s=1200"
```

**Response:**
```json
{
    "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
}
```

#### `GET /v1/surge` — Joukowsky surge pressure

**Parameters:**
- `wave_speed_m_s` (query, required, string) — Pressure-wave speed (m/s) Example: `1200`
- `velocity_change_m_s` (query, required, string) — Velocity change (m/s) Example: `2`
- `fluid_density_kg_m3` (query, optional, string) — Fluid density (kg/m³, default 998) Example: `998`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/waterhammer-api/v1/surge?wave_speed_m_s=1200&velocity_change_m_s=2&fluid_density_kg_m3=998"
```

**Response:**
```json
{
    "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
}
```

#### `GET /v1/wave-speed` — Pressure-wave speed in a pipe

**Parameters:**
- `fluid_density_kg_m3` (query, optional, string) — Fluid density (kg/m³, default 998) Example: `998`
- `bulk_modulus_gpa` (query, optional, string) — Fluid bulk modulus (GPa, default 2.2) Example: `2.2`
- `pipe_youngs_gpa` (query, optional, string) — Pipe Young's modulus (GPa) Example: `200`
- `pipe_diameter_mm` (query, optional, string) — Pipe inside diameter (mm) Example: `100`
- `wall_thickness_mm` (query, optional, string) — Pipe wall thickness (mm) Example: `5`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/waterhammer-api/v1/wave-speed?fluid_density_kg_m3=998&bulk_modulus_gpa=2.2&pipe_youngs_gpa=200&pipe_diameter_mm=100&wall_thickness_mm=5"
```

**Response:**
```json
{
    "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
}
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/waterhammer-api/v1/meta"
```

**Response:**
```json
{
    "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
}
```


---
Marketplace page: https://www.oanor.com/api/waterhammer-api
OpenAPI spec: https://www.oanor.com/api/waterhammer-api/openapi.json