# Swimming Pool Calculator API
> Swimming-pool maths as an API, computed locally and deterministically. The volume endpoint computes the water volume of a rectangular, round or oval pool — in litres, US gallons and cubic metres — from the dimensions and either an average depth or separate shallow and deep depths (it averages them), in feet or metres. The dose endpoint computes how much of a chemical to add to raise a level by a target ppm: give the pool volume and the desired increase, and either the product strength percent or a preset (cal-hypo, dichlor, trichlor, liquid chlorine, bleach), and it returns the amount in grams, kilograms, ounces and pounds. The salt endpoint computes the salt needed to reach a target salinity in a saltwater pool from the current and target ppm, in kilograms and pounds (and 40 lb bags). Everything is computed locally and deterministically, so it is instant and private. Dosing depends on the actual product strength and your test readings — always follow the product label, add in stages and re-test before adding more. Ideal for pool-service and maintenance apps, pool-builder and retailer tools, and smart-pool and home-automation systems. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is pool maths; for general volume or unit conversion use a unit-conversion 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/pool-api/..."
```

## Pricing
- **Free** (Free) — 9,635 calls/Mo, 2 req/s
- **Starter** ($11/Mo) — 19,250 calls/Mo, 8 req/s
- **Pro** ($31/Mo) — 242,500 calls/Mo, 20 req/s
- **Mega** ($69/Mo) — 1,255,000 calls/Mo, 50 req/s

## Endpoints

### Pool

#### `GET /v1/dose` — Chemical dose to raise ppm

**Parameters:**
- `volume_litres` (query, optional, string) — Volume in litres
- `volume_gallons` (query, optional, string) — Or US gallons Example: `5000`
- `ppm` (query, required, string) — ppm increase Example: `2`
- `chemical` (query, optional, string) — calhypo|dichlor|trichlor|liquidchlorine|bleach Example: `calhypo`
- `strength_percent` (query, optional, string) — Or product strength %

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/pool-api/v1/dose?volume_gallons=5000&ppm=2&chemical=calhypo"
```

**Response:**
```json
{
    "data": {
        "note": "Dose to raise the level by the given ppm. 1 ppm = 1 mg/L. Add in stages, circulate and re-test — never overshoot.",
        "grams": 58.24,
        "input": {
            "ppm": 2,
            "chemical": "calhypo",
            "volume_litres": 18927.1,
            "strength_percent": 65
        },
        "ounces": 2.054,
        "pounds": 0.1284,
        "kilograms": 0.0582
    },
    "meta": {
        "timestamp": "2026-06-03T17:41:58.252Z",
        "request_id": "c9d8a9d6-de58-4ff6-a5a2-4329c3668c26"
    },
    "status": "ok",
    "message": "Chemical dose",
    "success": true
}
```

#### `GET /v1/salt` — Salt for saltwater pool

**Parameters:**
- `volume_litres` (query, optional, string) — Volume in litres
- `volume_gallons` (query, optional, string) — Or US gallons Example: `5000`
- `current_ppm` (query, optional, string) — Current salinity (default 0) Example: `0`
- `target_ppm` (query, optional, string) — Target salinity (default 3200) Example: `3200`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/pool-api/v1/salt?volume_gallons=5000&current_ppm=0&target_ppm=3200"
```

**Response:**
```json
{
    "data": {
        "note": "Salt to raise from current to target ppm. Typical saltwater target is ~2700–3400 ppm; check your chlorinator's spec.",
        "input": {
            "target_ppm": 3200,
            "current_ppm": 0,
            "increase_ppm": 3200,
            "volume_litres": 18927.1
        },
        "salt_kg": 60.57,
        "salt_lb": 133.53,
        "bags_40lb": 4
    },
    "meta": {
        "timestamp": "2026-06-03T17:41:58.370Z",
        "request_id": "ad69916a-b0d3-4e3a-9f79-d802a252ae3e"
    },
    "status": "ok",
    "message": "Salt for saltwater pool",
    "success": true
}
```

#### `GET /v1/volume` — Pool water volume

**Parameters:**
- `shape` (query, optional, string) — rectangle|round|oval Example: `rectangle`
- `length` (query, optional, string) — Length Example: `32`
- `width` (query, optional, string) — Width Example: `16`
- `diameter` (query, optional, string) — Diameter (round)
- `depth` (query, optional, string) — Average depth Example: `5`
- `shallow` (query, optional, string) — Or shallow depth
- `deep` (query, optional, string) — And deep depth
- `unit` (query, optional, string) — ft|m (default ft) Example: `ft`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/pool-api/v1/volume?shape=rectangle&length=32&width=16&depth=5&unit=ft"
```

**Response:**
```json
{
    "data": {
        "note": "Volume uses the average depth. For a sloped floor, pass shallow and deep depths and it averages them.",
        "input": {
            "unit": "ft",
            "shape": "rectangle",
            "width": 16,
            "length": 32,
            "avg_depth": 5
        },
        "volume_m3": 72.491,
        "volume_litres": 72491.1,
        "volume_us_gallons": 19150.1
    },
    "meta": {
        "timestamp": "2026-06-03T17:41:58.465Z",
        "request_id": "7add16ee-12b7-4ed2-bea7-59e1156b0739"
    },
    "status": "ok",
    "message": "Pool volume",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "note": "Dosing depends on actual product strength and your test readings — follow the label and re-test before adding more.",
        "service": "pool",
        "chemicals": [
            "calhypo",
            "calciumhypochlorite",
            "dichlor",
            "trichlor",
            "liquidchlorine",
            "bleach",
            "sodiumhypochlorite"
        ],
        "endpoints": {
            "/v1/dose": "Grams/ounces of a chemical to raise a level by a target ppm, by product strength or preset.",
            "/v1/salt": "Salt (kg/lb) to reach a target salinity in a saltwater pool.",
            "/v1/volume": "Pool water volume (litres, US gallons, m³) for a rectangle, round or oval pool."
        },
        "description": "Swimming-pool maths: water volume by shape, chemical dosing to a target ppm, and salt for saltwater pools."
    },
    "meta": {
        "timestamp": "2026-06-03T17:41:58.604Z",
        "request_id": "b7811ea5-c935-4f4a-a8cb-4863b964675b"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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