# Rotational Grazing API
> Rotational-grazing maths as an API, computed locally and deterministically — the animal-unit, grazing-day and acreage numbers a rancher or homesteader moves a herd by. It all hangs on the animal unit: a 1000-pound cow eating about 26 pounds of dry matter a day. The animalunits endpoint converts a mixed herd to that common basis — a cow is 1.0 AU, a cow-calf pair 1.3, a horse 1.25, a sheep 0.2, a goat 0.17 — so ten cows and fifty sheep are 20 AU demanding 520 pounds of forage a day; pass a weight instead and it scales by weight ÷ 1000. The days endpoint works out how long a paddock lasts: grazing days = (acres × forage per acre × utilization) ÷ (animal units × 26), where the classic “take half, leave half” puts utilization near 50 %, so five acres yielding 3,000 lb at 50 % feeds 10 AU for about 29 days. The acres endpoint sizes the paddock the other way — acres = (AU × 26 × days) ÷ (forage × utilization) — so 20 AU for a 30-day move needs about 10.4 acres. Everything is computed locally and deterministically, so it is instant and private. Ideal for ranching, regenerative-agriculture, homesteading and farm-management app developers, paddock-planner and stocking-rate tools, and grazing-chart software. Pure local computation — no key, no third-party service, instant. US units; forage yield varies with season — measure it. Live, nothing stored. 3 compute endpoints.

## 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/grazing-api/..."
```

## Pricing
- **Free** (Free) — 6,440 calls/Mo, 2 req/s
- **Starter** ($4/Mo) — 53,600 calls/Mo, 6 req/s
- **Pro** ($12/Mo) — 224,200 calls/Mo, 15 req/s
- **Mega** ($39/Mo) — 1,308,000 calls/Mo, 40 req/s

## Endpoints

### Grazing

#### `GET /v1/acres` — Acreage for a herd & period

**Parameters:**
- `animal_units` (query, required, string) — Herd animal units Example: `20`
- `days` (query, required, string) — Grazing days Example: `30`
- `forage_lb_per_acre` (query, required, string) — Standing forage (lb DM/acre) Example: `3000`
- `utilization_percent` (query, optional, string) — Utilization % (default 50) Example: `50`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/grazing-api/v1/acres?animal_units=20&days=30&forage_lb_per_acre=3000&utilization_percent=50"
```

**Response:**
```json
{
    "data": {
        "note": "Acres = (animal units × 26 lb × days) ÷ (forage per acre × utilization). Size a paddock for the move interval (e.g. 1–3 days) and rest the rest of the pasture. Forage yield swings hugely with season and rainfall — measure it.",
        "inputs": {
            "days": 30,
            "animal_units": 20,
            "forage_lb_per_acre": 3000,
            "utilization_percent": 50
        },
        "acres_needed": 10.4,
        "forage_needed_lb": 15600,
        "usable_per_acre_lb": 1500
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:51.608Z",
        "request_id": "9ae98812-5fda-4a78-a8d6-569f5d0919d7"
    },
    "status": "ok",
    "message": "Acres needed",
    "success": true
}
```

#### `GET /v1/animalunits` — Herd → animal units

**Parameters:**
- `herd` (query, optional, string) — Comma list 'type:count' (cow, sheep, goat, horse, …) Example: `cow:10,sheep:50`
- `weight_lb` (query, optional, string) — Animal weight (lb) instead of a herd
- `count` (query, optional, string) — Number of animals (with weight_lb) Example: `1`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/grazing-api/v1/animalunits?herd=cow%3A10%2Csheep%3A50&count=1"
```

**Response:**
```json
{
    "data": {
        "note": "Animal units convert a mixed herd to a common basis: a cow is 1.0 AU, a cow-calf pair 1.3, a sheep 0.2, a goat 0.17, a horse 1.25. Total AU × 26 lb is the herd's daily dry-matter demand.",
        "inputs": {
            "herd": [
                {
                    "type": "cow",
                    "count": 10
                },
                {
                    "type": "sheep",
                    "count": 50
                }
            ]
        },
        "breakdown": [
            {
                "type": "cow",
                "count": 10,
                "animal_units": 10
            },
            {
                "type": "sheep",
                "count": 50,
                "animal_units": 10
            }
        ],
        "daily_intake_lb": 520,
        "total_animal_units": 20
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:51.709Z",
        "request_id": "dd0b2b13-f37f-4c2c-9e69-4aba42fea1b3"
    },
    "status": "ok",
    "message": "Animal units",
    "success": true
}
```

#### `GET /v1/days` — Grazing days for a paddock

**Parameters:**
- `acres` (query, required, string) — Paddock size (acres) Example: `5`
- `forage_lb_per_acre` (query, required, string) — Standing forage (lb DM/acre) Example: `3000`
- `animal_units` (query, required, string) — Herd animal units Example: `10`
- `utilization_percent` (query, optional, string) — Utilization % (default 50) Example: `50`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/grazing-api/v1/days?acres=5&forage_lb_per_acre=3000&animal_units=10&utilization_percent=50"
```

**Response:**
```json
{
    "data": {
        "note": "Grazing days = (acres × forage per acre × utilization) ÷ (animal units × 26 lb). 'Take half, leave half' — ~50 % utilization — keeps the sward healthy and regrowing. Move the herd before they graze it too short.",
        "inputs": {
            "acres": 5,
            "animal_units": 10,
            "forage_lb_per_acre": 3000,
            "utilization_percent": 50
        },
        "grazing_days": 28.8,
        "daily_demand_lb": 260,
        "available_forage_lb": 7500
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:51.804Z",
        "request_id": "3dc9c39d-fc4f-486f-a974-0b3bd27b038f"
    },
    "status": "ok",
    "message": "Grazing days",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "1 animal unit = a 1000 lb cow eating 26 lb dry matter/day. AU equivalents: cow 1.0, cow-calf 1.3, sheep 0.2, goat 0.17, horse 1.25. Use ~50 % utilization (take half, leave half). US units (acres, lb DM).",
        "service": "grazing-api",
        "endpoints": {
            "GET /v1/days": "Grazing days a paddock provides for a herd.",
            "GET /v1/meta": "This document.",
            "GET /v1/acres": "Acreage to graze a herd for a number of days.",
            "GET /v1/animalunits": "Total animal units from a herd list or by weight."
        },
        "description": "Rotational-grazing maths: animal units from a herd, grazing days a paddock provides, and acreage to graze a herd for a period."
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:51.903Z",
        "request_id": "8dcd5b05-5606-4494-abd1-2d0858d1e649"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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