# Aquarium Calculator API
> Aquarium maths as an API, computed locally and deterministically. The volume endpoint computes a tank's water volume — in US and UK gallons and litres — for a rectangular, cube, cylinder, hexagonal or bow-front tank from its dimensions (inches by default, or centimetres, millimetres and metres), and applies a fill factor (default 0.9) for substrate, decoration and freeboard to give a realistic net volume. The stocking endpoint gives a rough stocking load from the tank volume and the total length of fish using the classic inch-per-gallon guideline, reporting the maximum recommended inches and how heavily stocked the tank is. The waterchange endpoint computes the water-change volume for a percentage, with an optional dechlorinator dose. Everything is computed locally and deterministically, so it is instant and private. Stocking is a rough beginner guideline only — real stocking depends on the species, filtration and bioload. Ideal for aquarium and fishkeeping apps, pet-shop and hobbyist tools, and tank-setup planners. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is aquarium maths; for swimming-pool volume and chemical dosing use a pool API and for storage-tank gauging use a tank 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/aquarium-api/..."
```

## Pricing
- **Free** (Free) — 12,635 calls/Mo, 2 req/s
- **Starter** ($14/Mo) — 22,250 calls/Mo, 8 req/s
- **Pro** ($34/Mo) — 272,500 calls/Mo, 20 req/s
- **Mega** ($72/Mo) — 1,405,000 calls/Mo, 50 req/s

## Endpoints

### Aquarium

#### `GET /v1/stocking` — Stocking estimate

**Parameters:**
- `us_gallons` (query, optional, string) — Tank US gallons Example: `20`
- `litres` (query, optional, string) — Or litres
- `fish_inches` (query, required, string) — Total fish length (in) Example: `15`
- `inches_per_gallon` (query, optional, string) — Rule (default 1) Example: `1`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/aquarium-api/v1/stocking?us_gallons=20&fish_inches=15&inches_per_gallon=1"
```

**Response:**
```json
{
    "data": {
        "note": "Inch-per-gallon is a rough beginner guideline (use adult length, excluding the tail). Heavily bioloaded or large fish need much more.",
        "input": {
            "us_gallons": 20,
            "fish_inches": 15,
            "inches_per_gallon": 1
        },
        "status": "understocked",
        "load_percent": 75,
        "max_fish_inches": 20,
        "current_fish_inches": 15
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:12.770Z",
        "request_id": "03305938-3b64-4c6a-9194-8decfcf6cbca"
    },
    "status": "ok",
    "message": "Stocking estimate",
    "success": true
}
```

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

**Parameters:**
- `shape` (query, required, string) — rectangular|cube|cylinder|hexagonal|bowfront Example: `rectangular`
- `length` (query, optional, string) — Length Example: `24`
- `width` (query, optional, string) — Width Example: `12`
- `height` (query, optional, string) — Height Example: `16`
- `diameter` (query, optional, string) — Diameter (cylinder)
- `side` (query, optional, string) — Side (cube/hexagonal)
- `unit` (query, optional, string) — in|cm|mm|m (default in) Example: `in`
- `fill_factor` (query, optional, string) — Net factor (default 0.9) Example: `0.9`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/aquarium-api/v1/volume?shape=rectangular&length=24&width=12&height=16&unit=in&fill_factor=0.9"
```

**Response:**
```json
{
    "data": {
        "net": {
            "litres": 67.96,
            "uk_gallons": 14.949,
            "us_gallons": 17.953,
            "cubic_inches": 4147.2
        },
        "note": "Net volume applies a fill factor (default 0.9) for substrate, decor and freeboard. Gross is the full geometric volume.",
        "gross": {
            "litres": 75.51,
            "uk_gallons": 16.61,
            "us_gallons": 19.948,
            "cubic_inches": 4608
        },
        "input": {
            "unit": "in",
            "shape": "rectangular",
            "width": 12,
            "height": 16,
            "length": 24,
            "fill_factor": 0.9
        }
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:12.861Z",
        "request_id": "9d68ada2-04e5-45c0-8e15-f3a3b44fac64"
    },
    "status": "ok",
    "message": "Tank volume",
    "success": true
}
```

#### `GET /v1/waterchange` — Water change volume

**Parameters:**
- `us_gallons` (query, optional, string) — Tank US gallons Example: `20`
- `litres` (query, optional, string) — Or litres
- `percent` (query, optional, string) — Change % (default 25) Example: `25`
- `dechlorinator_ml_per_gallon` (query, optional, string) — Conditioner dose

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/aquarium-api/v1/waterchange?us_gallons=20&percent=25"
```

**Response:**
```json
{
    "data": {
        "note": "Change volume = tank volume × percent. Treat the new water with conditioner before adding.",
        "input": {
            "percent": 25,
            "us_gallons": 20
        },
        "change_litres": 18.93,
        "change_us_gallons": 5,
        "remaining_us_gallons": 15
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:12.950Z",
        "request_id": "410ea21f-0e6f-4e93-a93f-39af3f803e20"
    },
    "status": "ok",
    "message": "Water change volume",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "note": "Dimensions in inches by default (accepts cm/mm/m). Stocking is a rough guideline only.",
        "shapes": [
            "rectangular",
            "cube",
            "cylinder",
            "hexagonal",
            "bowfront"
        ],
        "service": "aquarium",
        "endpoints": {
            "/v1/volume": "Water volume (US/UK gallons, litres) for a rectangular, cube, cylinder, hexagonal or bow-front tank.",
            "/v1/stocking": "Stocking load from tank volume and total fish inches (inch-per-gallon guideline).",
            "/v1/waterchange": "Water-change volume for a percentage, with optional dechlorinator dose."
        },
        "description": "Aquarium maths: tank water volume by shape, a stocking estimate (inch-per-gallon) and water-change volume."
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:13.041Z",
        "request_id": "a4c37b41-b82b-47ee-9001-f412186a2d47"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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