# Chicken Coop API
> Backyard-chicken housing maths as an API, computed locally and deterministically — the coop, run and fixture numbers a flock keeper builds to. The space endpoint sizes the housing from the flock and the breed: about 4 ft² of coop floor per standard hen (2 for bantams, 5 for heavy breeds) plus roughly 10 ft² of run each, so ten standard hens want a 40 ft² coop and a 100 ft² run — and given a coop width it returns the length, or zero run for birds that free-range and only roost inside. The fixtures endpoint covers the inside: one nest box per three to four hens (they share and queue, so ten hens need three), 8–12 inches of roost bar per bird (ten birds ≈ 8.3 feet), about 4 inches of linear feeder space each, and a waterer per eight or so birds. Crowding is the root of pecking, disease and mess, so every figure rounds up and more space is always better; roosts should sit higher than the nest boxes so the birds don’t sleep — and soil — in them. Everything is computed locally and deterministically, so it is instant and private. Ideal for homesteading, backyard-poultry, farm and smallholding app developers, coop-planner and flock-management tools, and self-sufficiency software. Pure local computation — no key, no third-party service, instant. US units, rules of thumb. Live, nothing stored. 2 compute endpoints. For feed quantities use a different 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/chickencoop-api/..."
```

## Pricing
- **Free** (Free) — 6,700 calls/Mo, 2 req/s
- **Starter** ($4/Mo) — 56,600 calls/Mo, 6 req/s
- **Pro** ($12/Mo) — 231,500 calls/Mo, 15 req/s
- **Mega** ($37/Mo) — 1,351,000 calls/Mo, 40 req/s

## Endpoints

### Coop

#### `GET /v1/fixtures` — Nest boxes, roost, feeders

**Parameters:**
- `birds` (query, required, string) — Number of birds Example: `10`
- `hens_per_box` (query, optional, string) — Hens per nest box (default 4) Example: `4`
- `roost_in_per_bird` (query, optional, string) — Roost inches per bird (default 10) Example: `10`
- `feeder_in_per_bird` (query, optional, string) — Feeder inches per bird (default 4) Example: `4`
- `birds_per_waterer` (query, optional, string) — Birds per waterer (default 8) Example: `8`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/chickencoop-api/v1/fixtures?birds=10&hens_per_box=4&roost_in_per_bird=10&feeder_in_per_bird=4&birds_per_waterer=8"
```

**Response:**
```json
{
    "data": {
        "note": "One nest box per 3–4 hens (they share and queue), 8–12\" of roost bar per bird, ~4\" of linear feeder space each, and a waterer per ~8 birds. Roosts should sit higher than the nest boxes so birds don't sleep — and poop — in the nests.",
        "inputs": {
            "birds": 10,
            "hens_per_box": 4,
            "birds_per_waterer": 8,
            "roost_in_per_bird": 10,
            "feeder_in_per_bird": 4
        },
        "waterers": 2,
        "nest_boxes": 3,
        "roost_length_ft": 8.33,
        "roost_length_in": 100,
        "feeder_length_ft": 3.33,
        "feeder_length_in": 40
    },
    "meta": {
        "timestamp": "2026-06-06T07:13:59.821Z",
        "request_id": "c4ad1ec4-b230-4507-8a4a-052ead5051d3"
    },
    "status": "ok",
    "message": "Coop fixtures",
    "success": true
}
```

#### `GET /v1/space` — Coop & run sizing

**Parameters:**
- `birds` (query, required, string) — Number of birds Example: `10`
- `breed` (query, optional, string) — bantam, standard, large or heavy Example: `standard`
- `free_range` (query, optional, string) — true if birds free-range (run = 0) Example: `false`
- `coop_width_ft` (query, optional, string) — Coop width to get a length

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/chickencoop-api/v1/space?birds=10&breed=standard&free_range=false"
```

**Response:**
```json
{
    "data": {
        "note": "Rules of thumb: ~4 ft² of coop floor per standard hen (2 for bantams, 5 for heavy breeds) and ~10 ft² of run each. Crowding causes pecking and disease — more space is always better. Free-ranging birds need only the coop to roost in.",
        "inputs": {
            "birds": 10,
            "breed": "standard",
            "free_range": false
        },
        "run_sqft": 100,
        "coop_sqft": 40,
        "total_sqft": 140,
        "run_per_bird_sqft": 10,
        "coop_per_bird_sqft": 4
    },
    "meta": {
        "timestamp": "2026-06-06T07:13:59.922Z",
        "request_id": "c7cb5e98-9201-42cd-b71e-58b13c5560ae"
    },
    "status": "ok",
    "message": "Coop space",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "US units (ft², inches). Coop ~4 ft²/standard hen + run ~10 ft² each; 1 nest box per 3–4 hens; 8–12\" roost per bird. Rules of thumb — overcrowding causes problems, so round up. For feed quantities or pet nutrition use a different API.",
        "service": "chickencoop-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/space": "Coop and run floor area for a flock by breed size.",
            "GET /v1/fixtures": "Nest boxes, roost length and feeder/waterer space for a flock."
        },
        "description": "Backyard-chicken housing maths: coop and run sizing, and flock fixtures (nest boxes, roost, feeder & waterer)."
    },
    "meta": {
        "timestamp": "2026-06-06T07:14:00.019Z",
        "request_id": "a65312f2-0358-441b-b26b-fcea345654bd"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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