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

## 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/turnover-api/..."
```

## Pricing
- **Free** (Free) — 5,350 calls/Mo, 2 req/s
- **Starter** ($4/Mo) — 53,500 calls/Mo, 6 req/s
- **Pro** ($12/Mo) — 247,000 calls/Mo, 15 req/s
- **Mega** ($37/Mo) — 1,410,000 calls/Mo, 40 req/s

## Endpoints

### Turnover

#### `GET /v1/aquarium` — Filtration with head loss

**Parameters:**
- `tank_volume` (query, required, string) — Tank volume Example: `200`
- `pump_flow` (query, optional, string) — Rated pump flow/hr (for effective) Example: `1500`
- `target_turnovers_per_hour` (query, optional, string) — Or target ×/hr (for rated pump)
- `head_loss_percent` (query, optional, string) — Head loss % (default 40)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/turnover-api/v1/aquarium?tank_volume=200&pump_flow=1500"
```

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

#### `GET /v1/turnover` — Turnover time / required flow

**Parameters:**
- `volume` (query, required, string) — Water volume Example: `50000`
- `flow_rate` (query, optional, string) — Flow per hour (for turnover time) Example: `10000`
- `target_turnover_hours` (query, optional, string) — Or target turnover hours (for flow)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/turnover-api/v1/turnover?volume=50000&flow_rate=10000"
```

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

### Meta

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

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

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


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