# Pump Power API
> Pump power, head and affinity maths as an API, computed locally and deterministically. The power endpoint computes the power a pump needs from its flow rate, head, fluid density and efficiency: the hydraulic (water) power is ρ·g·Q·H, the shaft (brake) power is that divided by the pump efficiency, and an optional motor efficiency gives the electrical input power — all reported in watts, kilowatts and horsepower. Flow accepts litres per second or minute, cubic metres per hour or second and US gallons per minute; head accepts metres or feet; and the fluid can be water, seawater, oil, diesel and more, or a custom density. The head endpoint converts between pressure and head of fluid, H = P/(ρ·g), in both directions, across pascals, kPa, bar, psi and atmospheres. The affinity endpoint applies the pump affinity laws — flow scales with speed, head with speed squared and power with speed cubed — to predict the new operating point when you change the pump speed or trim the impeller diameter. Everything is computed locally and deterministically, so it is instant and private. Ideal for plumbing and HVAC tools, process and water-treatment engineering, irrigation and pool-pump apps, and energy-efficiency calculators. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is pump power and head maths; for flow rate from pipe diameter and velocity use a pipe-flow API and for open-channel flow use a Manning 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/pump-api/..."
```

## Pricing
- **Free** (Free) — 2,000 calls/Mo, 2 req/s
- **Starter** ($9/Mo) — 40,000 calls/Mo, 5 req/s
- **Pro** ($24/Mo) — 250,000 calls/Mo, 15 req/s
- **Mega** ($74/Mo) — 1,519,000 calls/Mo, 40 req/s

## Endpoints

### Pump

#### `GET /v1/affinity` — Pump affinity laws

**Parameters:**
- `speed_1` (query, optional, string) — Original speed (rpm) Example: `1450`
- `speed_2` (query, optional, string) — New speed (rpm) Example: `1740`
- `diameter_1` (query, optional, string) — Or original impeller diameter
- `diameter_2` (query, optional, string) — Or new impeller diameter
- `flow_1` (query, optional, string) — Original flow Example: `100`
- `head_1` (query, optional, string) — Original head Example: `20`
- `power_1` (query, optional, string) — Original power Example: `10`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/pump-api/v1/affinity?speed_1=1450&speed_2=1740&flow_1=100&head_1=20&power_1=10"
```

**Response:**
```json
{
    "data": {
        "note": "Affinity laws: Q ∝ N, H ∝ N², P ∝ N³ (same for impeller diameter trims).",
        "basis": "speed",
        "ratio": 1.2,
        "flow_2": 120,
        "head_2": 28.8,
        "factors": {
            "flow": 1.2,
            "head": 1.44,
            "power": 1.728
        },
        "power_2": 17.28
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:06.918Z",
        "request_id": "0a56009c-3ffa-4c4a-8fc4-4fffbda313b7"
    },
    "status": "ok",
    "message": "Pump affinity laws",
    "success": true
}
```

#### `GET /v1/head` — Pressure ↔ head

**Parameters:**
- `pressure` (query, optional, string) — Pressure (to get head) Example: `2`
- `pressure_unit` (query, optional, string) — pa|kpa|bar|psi|atm (default bar) Example: `bar`
- `head` (query, optional, string) — Or head (to get pressure)
- `head_unit` (query, optional, string) — m|ft Example: `m`
- `fluid` (query, optional, string) — Fluid (default water) Example: `water`
- `density` (query, optional, string) — Or explicit density

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/pump-api/v1/head?pressure=2&pressure_unit=bar&head_unit=m&fluid=water"
```

**Response:**
```json
{
    "data": {
        "head": {
            "m": 20.3943,
            "ft": 66.911
        },
        "mode": "pressure_to_head",
        "note": "H = P / (ρ·g).",
        "fluid": "water",
        "pressure_pa": 200000,
        "pressure_bar": 2,
        "density_kg_m3": 1000
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:06.980Z",
        "request_id": "ac66fe2d-ca74-4987-89b8-928b994837e1"
    },
    "status": "ok",
    "message": "Pressure <-> head conversion",
    "success": true
}
```

#### `GET /v1/power` — Pump hydraulic, shaft & motor power

**Parameters:**
- `flow` (query, required, string) — Flow rate Example: `50`
- `flow_unit` (query, optional, string) — ls|lmin|m3h|m3s|gpm (default ls) Example: `ls`
- `head` (query, required, string) — Head Example: `20`
- `head_unit` (query, optional, string) — m|ft (default m) Example: `m`
- `fluid` (query, optional, string) — water|seawater|oil|… (default water) Example: `water`
- `density` (query, optional, string) — Or explicit density (kg/m³)
- `efficiency` (query, optional, string) — Pump efficiency 0-1 (default 0.7) Example: `0.7`
- `motor_efficiency` (query, optional, string) — Motor efficiency 0-1

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/pump-api/v1/power?flow=50&flow_unit=ls&head=20&head_unit=m&fluid=water&efficiency=0.7"
```

**Response:**
```json
{
    "data": {
        "fluid": "water",
        "head_m": 20,
        "formula": "Hydraulic power = ρ·g·Q·H ; shaft power = hydraulic ÷ pump efficiency.",
        "flow_m3_s": 0.05,
        "shaft_power": {
            "hp": 18.787,
            "kW": 14.0095,
            "watts": 14009.5
        },
        "density_kg_m3": 1000,
        "hydraulic_power": {
            "hp": 13.1509,
            "kW": 9.80665,
            "watts": 9806.65
        },
        "pump_efficiency": 0.7
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:07.031Z",
        "request_id": "663caf87-e031-4855-bfe4-ab6700bf566b"
    },
    "status": "ok",
    "message": "Pump hydraulic, shaft & motor power",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "api": "pump",
        "note": "Pump power, head and affinity maths — computed locally and deterministically, no key, no third-party service.",
        "fluids": [
            "water",
            "seawater",
            "oil",
            "diesel",
            "petrol",
            "gasoline",
            "milk",
            "glycol"
        ],
        "endpoints": [
            "/v1/power",
            "/v1/head",
            "/v1/affinity",
            "/v1/meta"
        ],
        "flow_units": [
            "m3s",
            "m3/s",
            "ls",
            "l/s",
            "lps",
            "lmin",
            "l/min",
            "lpm",
            "m3h",
            "m3/h",
            "gpm"
        ]
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:07.121Z",
        "request_id": "24980505-6f36-43ae-be3f-8ce5ef070a0a"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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