# Aquascape API
> Planted-aquarium and aquascaping maths as an API, computed locally and deterministically — the dosing and water numbers a high-tech planted tank runs on, not the rolls of a dice. The co2 endpoint gives the dissolved CO2 concentration from pH and carbonate hardness using the classic relationship CO2 (ppm) ≈ 3 × KH (dKH) × 10^(7 − pH), and flags it against the 15–30 ppm window plants want — at pH 6.6 and KH 4 you are at about 30 ppm, the top of the safe zone, while pH 7.0 and KH 3 is a carbon-limited 9 ppm. The fertilizer endpoint turns a dry-salt dose into the nutrient ppm it adds, the heart of Estimative Index dosing: ppm = grams × the nutrient mass fraction × 1000 ÷ tank litres, so 1 g of KNO3 in 100 litres adds 6.1 ppm nitrate and 3.9 ppm potassium, and it knows KNO3, KH2PO4, K2SO4, MgSO4 (Epsom) and Ca(NO3)2. The substrate endpoint sizes the substrate from the footprint and target depth — a 60 × 30 cm tank at 6 cm deep needs 10.8 litres, two 9-litre aquasoil bags. Everything is computed locally and deterministically, so it is instant and private. Ideal for aquascaping and planted-tank apps, fertiliser-dosing calculators, CO2-rig tools, and aquarium-shop and hobby sites. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 compute endpoints. For a tank water volume or fish stocking use an aquarium API; for pool chemistry use a pool 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/aquascape-api/..."
```

## Pricing
- **Free** (Free) — 300 calls/Mo, 2 req/s
- **Starter** ($5/Mo) — 9,000 calls/Mo, 6 req/s
- **Pro** ($17/Mo) — 60,000 calls/Mo, 14 req/s
- **Mega** ($52/Mo) — 210,000 calls/Mo, 34 req/s

## Endpoints

### Aquascape

#### `GET /v1/co2` — Dissolved CO2 from pH and KH

**Parameters:**
- `ph` (query, required, string) — Tank pH Example: `6.6`
- `kh_dkh` (query, required, string) — Carbonate hardness in dKH Example: `4`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/aquascape-api/v1/co2?ph=6.6&kh_dkh=4"
```

**Response:**
```json
{
    "data": {
        "note": "Dissolved CO2 ≈ 3 × KH (dKH) × 10^(7 − pH). The 15–30 ppm window suits a high-tech planted tank; above ~30 ppm fish start to suffer, so add CO2 gradually and watch livestock at lights-on. The pH/KH method assumes carbonate buffering only — tannins, phosphate buffers or non-carbonate KH throw it off; a drop checker is the real-time cross-check.",
        "level": "high — risk to fish, watch for gasping",
        "inputs": {
            "ph": 6.6,
            "kh_dkh": 4
        },
        "co2_ppm": 30.1
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:47.466Z",
        "request_id": "f81c9d37-cf52-428b-8b5b-5cacdbae98d3"
    },
    "status": "ok",
    "message": "CO2 from pH/KH",
    "success": true
}
```

#### `GET /v1/fertilizer` — Nutrient ppm from a dry-salt dose

**Parameters:**
- `salt` (query, required, string) — kno3 | kh2po4 | k2so4 | mgso4 | cano3 Example: `kno3`
- `grams` (query, required, string) — Grams dosed Example: `1`
- `tank_liters` (query, required, string) — Net tank volume in litres Example: `100`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/aquascape-api/v1/fertilizer?salt=kno3&grams=1&tank_liters=100"
```

**Response:**
```json
{
    "data": {
        "note": "ppm added = grams × the nutrient's mass fraction × 1000 ÷ tank litres (use the net water volume, not the tank rating). Estimative Index aims for weekly NO3 ~10–30, PO4 ~1–3, K ~10–30 ppm with a 50 % water change to reset. Dry-dose into the tank or mix a stock solution — and always add MgSO4 and Ca separately from phosphate to avoid precipitation.",
        "inputs": {
            "salt": "kno3",
            "grams": 1,
            "tank_liters": 100
        },
        "ppm_added": {
            "K": 3.867,
            "NO3": 6.133
        },
        "salt_name": "KNO3 (potassium nitrate)"
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:47.574Z",
        "request_id": "05e3a5ab-b873-46c8-8c9b-d622c3f5b859"
    },
    "status": "ok",
    "message": "Fertilizer ppm",
    "success": true
}
```

#### `GET /v1/substrate` — Substrate volume and bags

**Parameters:**
- `length_cm` (query, required, string) — Footprint length in cm Example: `60`
- `width_cm` (query, required, string) — Footprint width in cm Example: `30`
- `depth_cm` (query, optional, string) — Target depth in cm (default 6) Example: `6`
- `bag_liters` (query, optional, string) — Bag size in litres (default 9) Example: `9`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/aquascape-api/v1/substrate?length_cm=60&width_cm=30&depth_cm=6&bag_liters=9"
```

**Response:**
```json
{
    "data": {
        "note": "Substrate volume = footprint area × depth. A planted tank wants ~5–8 cm, sloped deeper at the back for depth and rooting; carpets and big root-feeders like the upper end. Aquasoil bags are commonly ~9 L — set bag_liters for your product. Buy a little extra for a slope.",
        "inputs": {
            "depth_cm": 6,
            "width_cm": 30,
            "length_cm": 60,
            "bag_liters": 9
        },
        "bags_needed": 2,
        "substrate_liters": 10.8
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:47.677Z",
        "request_id": "f570017b-c498-4f4d-a803-a5e5ef2a77b2"
    },
    "status": "ok",
    "message": "Substrate volume",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "CO2 = 3·KH·10^(7−pH); ppm = g × fraction × 1000 ÷ litres; substrate = footprint × depth. Salts: kno3, kh2po4, k2so4, mgso4, cano3. Educational — for a tank's water volume or fish stocking use an aquarium API; for pool chemistry use a pool API.",
        "service": "aquascape-api",
        "endpoints": {
            "GET /v1/co2": "Dissolved CO2 (ppm) from pH and carbonate hardness (KH).",
            "GET /v1/meta": "This document.",
            "GET /v1/substrate": "Substrate volume and bags from footprint and target depth.",
            "GET /v1/fertilizer": "Nutrient ppm added by dosing a dry salt (EI dry dosing)."
        },
        "description": "Planted-aquarium / aquascaping maths: dissolved CO2 from pH & KH, dry-fertiliser dosing in ppm, and substrate volume."
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:47.778Z",
        "request_id": "94403b64-e3b9-4f1f-a386-2fee70939bf3"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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