# Tank Volume API
> Tank volume and fill-level maths as an API, computed locally and deterministically. The volume endpoint gives the total capacity — in litres, US gallons and cubic metres — of a vertical cylinder, horizontal cylinder, rectangular tank, sphere or capsule, from its dimensions in metres, centimetres, millimetres, feet or inches. The fill endpoint computes the volume of liquid and the percent full at a given fill depth, using the exact geometry for each shape — including the circular-segment formula for a horizontal cylinder (where the level is famously non-linear) and the spherical-cap formula for a sphere. The level endpoint is the inverse "dipstick" calculation: it finds the depth that corresponds to a target volume or a target percentage, solving the segment geometry by bisection. Everything is computed locally and deterministically, so it is instant and private. Ideal for fuel, water, oil and chemical tank monitoring, agriculture and irrigation, process and industrial tooling, and tank-gauging and dipstick apps. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is tank-gauging geometry; for swimming-pool volume and chemical dosing use a pool API, and for plain 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/tank-api/..."
```

## Pricing
- **Free** (Free) — 9,835 calls/Mo, 2 req/s
- **Starter** ($11/Mo) — 19,450 calls/Mo, 8 req/s
- **Pro** ($31/Mo) — 244,500 calls/Mo, 20 req/s
- **Mega** ($69/Mo) — 1,265,000 calls/Mo, 50 req/s

## Endpoints

### Tank

#### `GET /v1/fill` — Volume & % full at a depth

**Parameters:**
- `shape` (query, required, string) — Tank shape Example: `horizontal-cylinder`
- `diameter` (query, optional, string) — Diameter (or radius) Example: `2`
- `length` (query, optional, string) — Length Example: `5`
- `depth` (query, required, string) — Fill depth Example: `1`
- `unit` (query, optional, string) — m|cm|mm|ft|in Example: `m`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/tank-api/v1/fill?shape=horizontal-cylinder&diameter=2&length=5&depth=1&unit=m"
```

**Response:**
```json
{
    "data": {
        "note": "Filled volume at the given depth. Horizontal cylinders and spheres use the exact circular-segment / spherical-cap formulas.",
        "input": {
            "unit": "m",
            "depth": 1,
            "shape": "horizontalcylinder",
            "length": 5,
            "radius": 1
        },
        "filled": {
            "m3": 7.85398,
            "litres": 7853.98,
            "us_gallons": 2074.8
        },
        "capacity": {
            "m3": 15.70796,
            "litres": 15707.96,
            "us_gallons": 4149.6
        },
        "remaining": {
            "m3": 7.85398,
            "litres": 7853.98,
            "us_gallons": 2074.8
        },
        "percent_full": 50
    },
    "meta": {
        "timestamp": "2026-06-03T17:41:57.364Z",
        "request_id": "306a4a6f-72c9-451b-ae1c-bc0d9fa1e9be"
    },
    "status": "ok",
    "message": "Filled volume at depth",
    "success": true
}
```

#### `GET /v1/level` — Dipstick depth for a target

**Parameters:**
- `shape` (query, required, string) — Tank shape Example: `horizontal-cylinder`
- `diameter` (query, optional, string) — Diameter (or radius) Example: `2`
- `length` (query, optional, string) — Length Example: `5`
- `percent` (query, optional, string) — Target % full Example: `75`
- `litres` (query, optional, string) — Or target litres
- `unit` (query, optional, string) — m|cm|mm|ft|in Example: `m`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/tank-api/v1/level?shape=horizontal-cylinder&diameter=2&length=5&percent=75&unit=m"
```

**Response:**
```json
{
    "data": {
        "note": "Dipstick depth for the target fill, found by bisection (exact for the linear shapes).",
        "depth": 1.404,
        "input": {
            "unit": "m",
            "shape": "horizontalcylinder",
            "length": 5,
            "radius": 1
        },
        "target": {
            "m3": 11.78097,
            "litres": 11780.97,
            "us_gallons": 3112.2
        },
        "depth_m": 1.40397,
        "depth_unit": "m",
        "percent_full": 75
    },
    "meta": {
        "timestamp": "2026-06-03T17:41:57.470Z",
        "request_id": "3eef9a21-bdeb-42e5-b6ba-33525c8f24ab"
    },
    "status": "ok",
    "message": "Dipstick depth for target",
    "success": true
}
```

#### `GET /v1/volume` — Total tank capacity

**Parameters:**
- `shape` (query, required, string) — vertical-cylinder|horizontal-cylinder|rectangle|sphere|capsule Example: `horizontal-cylinder`
- `diameter` (query, optional, string) — Diameter (or radius) Example: `2`
- `radius` (query, optional, string) — Radius
- `length` (query, optional, string) — Length (h-cyl/capsule/rect) Example: `5`
- `width` (query, optional, string) — Width (rect)
- `height` (query, optional, string) — Height (v-cyl/rect)
- `unit` (query, optional, string) — m|cm|mm|ft|in (default m) Example: `m`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/tank-api/v1/volume?shape=horizontal-cylinder&diameter=2&length=5&unit=m"
```

**Response:**
```json
{
    "data": {
        "note": "Total tank capacity. Use /v1/fill for the volume at a given depth.",
        "input": {
            "unit": "m",
            "shape": "horizontalcylinder",
            "length": 5,
            "radius": 1
        },
        "capacity": {
            "m3": 15.70796,
            "litres": 15707.96,
            "us_gallons": 4149.6
        },
        "max_depth_m": 2
    },
    "meta": {
        "timestamp": "2026-06-03T17:41:57.573Z",
        "request_id": "311544b8-4b7d-42e7-8af1-058b3c43bacd"
    },
    "status": "ok",
    "message": "Tank capacity",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "note": "Dimensions in your chosen unit (m default). Volumes returned in m³, litres and US gallons.",
        "units": [
            "m",
            "cm",
            "mm",
            "ft",
            "in"
        ],
        "shapes": [
            "vertical-cylinder",
            "horizontal-cylinder",
            "rectangle",
            "sphere",
            "capsule"
        ],
        "service": "tank",
        "endpoints": {
            "/v1/fill": "Filled volume and percent full at a given depth (exact circular-segment / spherical-cap maths).",
            "/v1/level": "Inverse dipstick: the depth that gives a target volume or percent.",
            "/v1/volume": "Total capacity (litres/US gallons/m³) for vertical/horizontal cylinder, rectangle, sphere or capsule."
        },
        "description": "Tank volume and fill-level maths: capacity by shape, volume at a depth, and the dipstick depth for a target fill."
    },
    "meta": {
        "timestamp": "2026-06-03T17:41:57.653Z",
        "request_id": "8dd722c9-e276-4f49-8157-b7368e0bc9cb"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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