# Garden Pond API
> Garden and koi-pond maths as an API, computed locally and deterministically — the numbers behind a backyard water feature, so you do not have to guess at the hose. The volume endpoint turns length, width and average depth into the water volume in cubic feet, US gallons and litres, applying a shape factor (rectangular 1.0, oval or round 0.79, irregular 0.85) because a liner pond never holds the full bounding box: an 8 × 6 ft pond two feet deep is about 96 cubic feet, or 718 gallons. The liner endpoint sizes the flexible liner to fit a pond — length equals the pond length plus twice the maximum depth plus twice the overlap to anchor under the edging stones (same for width), so that same 8 × 6 pond at two feet deep with a one-foot overlap needs a 14 × 12 ft liner and matching underlayment. The stock endpoint turns a water volume into a safe fish load and the pump you need: roughly one koi per 250 gallons (they grow large and dirty) or one goldfish per 20, plus the pump flow in gallons per hour to turn the whole pond over at least once an hour for koi — 718 gallons holds about two koi and wants a ~720 GPH pump before head-height losses. Everything is computed locally and deterministically, so it is instant and private. Ideal for landscaping and pond-installer tools, garden-design and home-improvement apps, koi and water-garden hobbyist sites, and aquascaping calculators. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 compute endpoints. For pool chemistry use a pool API; for indoor fish tanks use an aquarium 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/pond-api/..."
```

## Pricing
- **Free** (Free) — 200 calls/Mo, 2 req/s
- **Starter** ($5/Mo) — 6,000 calls/Mo, 5 req/s
- **Pro** ($17/Mo) — 40,000 calls/Mo, 12 req/s
- **Mega** ($48/Mo) — 150,000 calls/Mo, 30 req/s

## Endpoints

### Pond

#### `GET /v1/liner` — Liner size to fit a pond

**Parameters:**
- `length_ft` (query, required, string) — Pond length in feet Example: `8`
- `width_ft` (query, required, string) — Pond width in feet Example: `6`
- `max_depth_ft` (query, required, string) — Maximum depth in feet Example: `2`
- `overlap_ft` (query, optional, string) — Edge overlap in feet (default 1) Example: `1`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/pond-api/v1/liner?length_ft=8&width_ft=6&max_depth_ft=2&overlap_ft=1"
```

**Response:**
```json
{
    "data": {
        "note": "Liner length = pond length + 2 × max depth + 2 × overlap (same for width). The depth wraps up both sides and you need ~1 ft of overlap each edge to anchor under stone. Add underlayment of the same size to protect against punctures.",
        "inputs": {
            "width_ft": 6,
            "length_ft": 8,
            "overlap_ft": 1,
            "max_depth_ft": 2
        },
        "liner_width_ft": 12,
        "liner_area_sqft": 168,
        "liner_length_ft": 14
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:48.284Z",
        "request_id": "438d2215-bacb-4483-97b7-7bb145e951c3"
    },
    "status": "ok",
    "message": "Liner size",
    "success": true
}
```

#### `GET /v1/stock` — Fish stocking and pump turnover

**Parameters:**
- `gallons` (query, required, string) — Pond volume in gallons Example: `718`
- `turnover_hours` (query, optional, string) — Hours per full turnover (default 1) Example: `1`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/pond-api/v1/stock?gallons=718&turnover_hours=1"
```

**Response:**
```json
{
    "data": {
        "note": "Stocking: about 1 koi per 250 gallons (they grow big and dirty) or 1 goldfish per 20. Circulate the whole pond at least once an hour for koi — pump GPH = gallons ÷ turnover hours, and size up for head height and tubing losses. Under-stock and over-filter for clear water.",
        "inputs": {
            "gallons": 718,
            "turnover_hours": 1
        },
        "max_koi": 2,
        "max_goldfish": 35,
        "pump_gph_for_turnover": 718
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:48.383Z",
        "request_id": "e0cb4d96-7b22-43ad-8f1d-b8c79e39c6d1"
    },
    "status": "ok",
    "message": "Fish stocking",
    "success": true
}
```

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

**Parameters:**
- `length_ft` (query, required, string) — Pond length in feet Example: `8`
- `width_ft` (query, required, string) — Pond width in feet Example: `6`
- `avg_depth_ft` (query, required, string) — Average depth in feet Example: `2`
- `shape` (query, optional, string) — rectangular | oval | round | irregular Example: `rectangular`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/pond-api/v1/volume?length_ft=8&width_ft=6&avg_depth_ft=2&shape=rectangular"
```

**Response:**
```json
{
    "data": {
        "note": "Volume = length × width × average depth × a shape factor (rectangular 1.0, oval/round 0.79, irregular 0.85), then 7.48 gallons per cubic foot. Use the AVERAGE depth, not the deepest point. A liner pond rarely holds the full box.",
        "inputs": {
            "shape": "rectangular",
            "width_ft": 6,
            "length_ft": 8,
            "avg_depth_ft": 2
        },
        "liters": 2718,
        "gallons": 718,
        "cubic_feet": 96,
        "shape_factor": 1
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:48.458Z",
        "request_id": "e78100a7-b663-43b1-80b2-0831f6274532"
    },
    "status": "ok",
    "message": "Pond volume",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "US units (feet, gallons). Volume × shape factor × 7.48 gal/ft³; liner = dimension + 2·depth + 2·overlap; koi ~1/250 gal, goldfish ~1/20, turnover ≥ once an hour. For pool chemistry or indoor aquariums use a different API.",
        "service": "pond-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/liner": "Liner length and width to fit a pond, with depth and overlap.",
            "GET /v1/stock": "Max koi/goldfish and the pump GPH for turnover from a volume.",
            "GET /v1/volume": "Pond volume (gallons/litres) from length, width and average depth."
        },
        "description": "Garden / koi pond maths: water volume, liner size, and fish stocking with pump turnover."
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:48.553Z",
        "request_id": "bddbf3a6-f952-4fb3-8835-c46a83dad1fa"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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