# Composting API
> Composting maths as an API, computed locally and deterministically — the three numbers that decide whether a pile heats up and breaks down or sits there cold and smelly. The cn-ratio endpoint blends a mix to its carbon-to-nitrogen ratio: pass each material by weight with its dry-weight %C and %N as parallel comma-separated lists and it returns the total carbon and nitrogen masses and the blended C:N, with an assessment against the ideal 25–35:1 — ten parts dry leaves (50 %C, 1 %N) with ten parts grass clippings (45 %C, 2.5 %N) comes out at a near-perfect 27:1. The moisture endpoint works out the water to add to reach a target moisture (the pile should be a wrung-out-sponge 50–60 %): from the current mass and moisture it holds the dry matter constant, so 100 kg at 30 % needs about 56 kg of water to reach 55 %, and it flags a too-wet pile that needs drying instead. The mix endpoint gives the brown:green weight ratio to hit a target C:N from two materials' %C and %N — leaves and grass at a target 30:1 want about 1.5 parts browns to 1 part greens. Everything is computed locally and deterministically, so it is instant and private. Ideal for gardening and composting apps, master-composter and allotment tools, regenerative-ag and soil-health sites, and waste-diversion calculators. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 compute endpoints. For material volume use a mulch API; for NPK application rates use a fertilizer 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/compost-api/..."
```

## Pricing
- **Free** (Free) — 450 calls/Mo, 2 req/s
- **Starter** ($5/Mo) — 12,500 calls/Mo, 6 req/s
- **Pro** ($17/Mo) — 80,000 calls/Mo, 15 req/s
- **Mega** ($50/Mo) — 260,000 calls/Mo, 36 req/s

## Endpoints

### Compost

#### `GET /v1/cn-ratio` — Blended carbon-to-nitrogen ratio

**Parameters:**
- `weights` (query, required, string) — Comma-separated material weights Example: `10,10`
- `carbon_pct` (query, required, string) — Comma-separated dry-weight %C Example: `50,45`
- `nitrogen_pct` (query, required, string) — Comma-separated dry-weight %N Example: `1,2.5`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/compost-api/v1/cn-ratio?weights=10%2C10&carbon_pct=50%2C45&nitrogen_pct=1%2C2.5"
```

**Response:**
```json
{
    "data": {
        "note": "Blended C:N = total carbon mass ÷ total nitrogen mass, where each material contributes weight × its dry-weight %. Aim for about 25–35:1 — greens (grass, manure, kitchen scraps) are nitrogen-rich and low C:N, browns (dry leaves, straw, cardboard) are carbon-rich and high C:N. Pass dry-weight %C and %N for each material as parallel comma-separated lists.",
        "inputs": {
            "weights": [
                10,
                10
            ],
            "carbon_pct": [
                50,
                45
            ],
            "nitrogen_pct": [
                1,
                2.5
            ]
        },
        "cn_ratio": 27.1,
        "assessment": "ideal — heats up and breaks down efficiently",
        "carbon_mass": 9.5,
        "nitrogen_mass": 0.35
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:45.744Z",
        "request_id": "f85a3afd-afd6-4c68-8fd6-a691f3f716e0"
    },
    "status": "ok",
    "message": "C:N ratio",
    "success": true
}
```

#### `GET /v1/mix` — Brown:green ratio for a target C:N

**Parameters:**
- `brown_carbon_pct` (query, required, string) — Brown %C Example: `50`
- `brown_nitrogen_pct` (query, required, string) — Brown %N Example: `1`
- `green_carbon_pct` (query, required, string) — Green %C Example: `45`
- `green_nitrogen_pct` (query, required, string) — Green %N Example: `2.5`
- `target_cn` (query, optional, string) — Target C:N (default 30) Example: `30`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/compost-api/v1/mix?brown_carbon_pct=50&brown_nitrogen_pct=1&green_carbon_pct=45&green_nitrogen_pct=2.5&target_cn=30"
```

**Response:**
```json
{
    "data": {
        "note": "To hit a target C:N from two materials, weight ratio brown:green = (green %C − target × green %N) ÷ (target × brown %N − brown %C). The target must sit between the two materials' own C:N ratios, or no positive mix reaches it. Mix by weight, then check moisture.",
        "inputs": {
            "target_cn": 30,
            "brown_carbon_pct": 50,
            "green_carbon_pct": 45,
            "brown_nitrogen_pct": 1,
            "green_nitrogen_pct": 2.5
        },
        "brown_cn": 50,
        "green_cn": 18,
        "brown_to_green_ratio": 1.5
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:45.845Z",
        "request_id": "1adc6851-55ba-4d50-a784-e8523dd05944"
    },
    "status": "ok",
    "message": "Mix ratio",
    "success": true
}
```

#### `GET /v1/moisture` — Water for a target moisture

**Parameters:**
- `mass` (query, required, string) — Current total mass (kg or lb) Example: `100`
- `current_moisture_pct` (query, required, string) — Current moisture % Example: `30`
- `target_moisture_pct` (query, optional, string) — Target moisture % (default 55) Example: `55`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/compost-api/v1/moisture?mass=100&current_moisture_pct=30&target_moisture_pct=55"
```

**Response:**
```json
{
    "data": {
        "note": "A compost pile wants ~50–60 % moisture — damp like a wrung-out sponge. Water to add = dry mass ÷ (1 − target) − current mass, holding the dry matter constant. A negative result means it is too wet; turn it and mix in dry browns. Same unit in and out (kg or lb).",
        "inputs": {
            "mass": 100,
            "target_moisture_pct": 55,
            "current_moisture_pct": 30
        },
        "dry_mass": 70,
        "direction": "add water",
        "water_to_add": 55.56,
        "new_total_mass": 155.56
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:45.955Z",
        "request_id": "34aee6a9-954d-4cfb-8b51-449bfdcc8c0e"
    },
    "status": "ok",
    "message": "Moisture",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "Carbon/nitrogen as dry-weight %. Target C:N ≈ 25–35:1, moisture ≈ 50–60 %. For material volume (area × depth) use a mulch API; for NPK application rates use a fertilizer API.",
        "service": "compost-api",
        "endpoints": {
            "GET /v1/mix": "Brown:green weight ratio to hit a target C:N from each material's %C and %N.",
            "GET /v1/meta": "This document.",
            "GET /v1/cn-ratio": "Blended C:N from materials by weight, %C and %N (parallel CSV lists).",
            "GET /v1/moisture": "Water to add to reach a target moisture from a current moisture."
        },
        "description": "Composting maths: blended carbon-to-nitrogen ratio, water for a target moisture, and the brown:green ratio to hit a target C:N."
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:46.046Z",
        "request_id": "79d6b56b-f81d-416c-aa81-964dc215f83a"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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