# Aquaculture API
> Fish-farming (aquaculture) maths as an API, computed locally and deterministically — the stocking, feed and oxygen numbers a fish farmer or RAS designer runs a system on. The stocking endpoint turns a tank or pond volume and a target biomass density into a fish count: biomass = density × volume, count = biomass ÷ average fish weight — a 10 m³ tank at 30 kg/m³ holds 300 kg, about 1,200 fish at 250 g each, and you stock to the harvest weight, not the fingerling weight, so the tank does not overload as they grow. The feed endpoint gives the daily ration as a percentage of body weight, and the feed to reach a target weight gain through the feed conversion ratio — 300 kg fed at 2 % is 6 kg a day, and growing 100 kg of fish at an FCR of 1.2 takes 120 kg of feed. The oxygen endpoint gives the dissolved-oxygen demand of a stock — biomass × the per-kg consumption rate — so 300 kg at 300 mg O₂/kg/hr needs 90 g of oxygen an hour, the number your aeration must beat. Everything is computed locally and deterministically, so it is instant and private. Ideal for aquaculture and RAS-design apps, fish-farm management tools, hatchery and feed calculators, and ag-tech sites. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 compute endpoints. Commercial-planning estimates — species and system vary. For a home aquarium 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/aquaculture-api/..."
```

## Pricing
- **Free** (Free) — 300 calls/Mo, 2 req/s
- **Starter** ($6/Mo) — 8,000 calls/Mo, 5 req/s
- **Pro** ($19/Mo) — 52,000 calls/Mo, 13 req/s
- **Mega** ($55/Mo) — 180,000 calls/Mo, 32 req/s

## Endpoints

### Aquaculture

#### `GET /v1/feed` — Daily ration and feed for gain

**Parameters:**
- `biomass_kg` (query, required, string) — Total biomass in kg Example: `300`
- `feed_rate_pct` (query, optional, string) — Feeding rate % body weight/day (default 2) Example: `2`
- `target_gain_kg` (query, optional, string) — Target weight gain in kg Example: `100`
- `fcr` (query, optional, string) — Feed conversion ratio (default 1.2) Example: `1.2`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/aquaculture-api/v1/feed?biomass_kg=300&feed_rate_pct=2&target_gain_kg=100&fcr=1.2"
```

**Response:**
```json
{
    "data": {
        "fcr": 1.2,
        "note": "Daily ration = biomass × the feeding rate (% of body weight/day) — smaller, warmer fish eat a higher percentage, large fish less. To reach a target gain, feed = gain × FCR (feed conversion ratio): a good pellet diet runs an FCR around 1.0–1.5, so it takes ~1.2 kg of feed per kg of fish grown. Overfeeding wastes money and fouls the water.",
        "inputs": {
            "biomass_kg": 300,
            "feed_rate_pct": 2
        },
        "daily_feed_kg": 6,
        "feed_for_gain_kg": 120
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:42.653Z",
        "request_id": "60d5130a-9ddf-442f-82a4-1058724088f4"
    },
    "status": "ok",
    "message": "Feed",
    "success": true
}
```

#### `GET /v1/oxygen` — Dissolved-oxygen demand

**Parameters:**
- `biomass_kg` (query, required, string) — Total biomass in kg Example: `300`
- `consumption_mg_kg_hr` (query, optional, string) — O₂ use mg/kg/hr (default 300) Example: `300`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/aquaculture-api/v1/oxygen?biomass_kg=300&consumption_mg_kg_hr=300"
```

**Response:**
```json
{
    "data": {
        "note": "Oxygen demand = biomass × the per-kg consumption rate, which rises with temperature, feeding and stress (≈200–500 mg O₂ per kg per hour for many farmed fish). Your aeration or oxygenation must meet this plus a margin, and keep dissolved oxygen above ~5–6 mg/L — oxygen, not space, is usually what caps stocking density.",
        "inputs": {
            "biomass_kg": 300,
            "consumption_mg_kg_hr": 300
        },
        "o2_demand_g_hr": 90,
        "o2_demand_g_day": 2160,
        "o2_demand_mg_hr": 90000
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:42.740Z",
        "request_id": "4fb2f8a0-c8f0-46ef-bbfb-3ef060ab4442"
    },
    "status": "ok",
    "message": "Oxygen demand",
    "success": true
}
```

#### `GET /v1/stocking` — Fish count from biomass density

**Parameters:**
- `volume_m3` (query, required, string) — System volume in m³ Example: `10`
- `density_kg_m3` (query, optional, string) — Target biomass density kg/m³ (default 30) Example: `30`
- `avg_weight_g` (query, required, string) — Average fish weight in grams Example: `250`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/aquaculture-api/v1/stocking?volume_m3=10&density_kg_m3=30&avg_weight_g=250"
```

**Response:**
```json
{
    "data": {
        "note": "Stock count = target biomass ÷ average fish weight, where biomass = density × volume. Safe density depends on species and system — flow-through and pond systems run lighter, a well-oxygenated RAS far heavier (trout 40–80 kg/m³). Stock to the HARVEST weight, not the fingerling weight, or the tank overloads as they grow.",
        "inputs": {
            "volume_m3": 10,
            "avg_weight_g": 250,
            "density_kg_m3": 30
        },
        "fish_count": 1200,
        "max_biomass_kg": 300
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:42.827Z",
        "request_id": "1f509ebf-6dc2-4894-89f2-2039b8ceb2c3"
    },
    "status": "ok",
    "message": "Stocking",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "SI units (m³, kg, g). biomass = density × volume; ration = biomass × rate%; feed-for-gain = gain × FCR; O₂ demand = biomass × mg/kg/hr. Commercial/RAS planning estimates — species and system vary. For a home aquarium use an aquarium API.",
        "service": "aquaculture-api",
        "endpoints": {
            "GET /v1/feed": "Daily ration by body weight, and feed for a target gain via FCR.",
            "GET /v1/meta": "This document.",
            "GET /v1/oxygen": "Dissolved-oxygen demand of a stock (mg/hr, g/hr, g/day).",
            "GET /v1/stocking": "Fish count a volume holds at a target biomass density."
        },
        "description": "Aquaculture (fish-farming) maths: stocking from biomass density, daily feed by body weight and FCR, and the dissolved-oxygen demand of a stock."
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:42.919Z",
        "request_id": "3dd4f007-29ac-4ee5-a64e-365901669d5a"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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