# Animal Gestation API
> Animal gestation and egg-incubation date maths as an API, computed locally and deterministically — the breeding and hatch calendar a farmer, breeder or vet works to. The gestation endpoint takes a species and a breeding date and returns the expected due date with the normal early-to-late window: due date = breeding date + the species' average gestation, so a cow bred on the 1st of January (283 days) calves around the 11th of October, a dog (63 days) whelps nine weeks later, a goat 150 days, a horse 340, a pig 114 — dozens of species from rabbit to camel to elephant, with an override for your own herd average. Give a target birth date instead and it works backwards to the date to breed. The incubation endpoint does the same for poultry and birds — chicken 21 days, duck 28, goose 30, quail 18, ostrich 42 and more — returning the hatch date, the lockdown date (stop turning and raise humidity ~3 days before hatch) and the day-7 and day-14 candling dates. Date arithmetic is exact, including leap years. Everything is computed locally and deterministically, so it is instant and private. Ideal for livestock, breeding, veterinary, farm-management and hatchery app developers, gestation-calculator and breeding-calendar tools, and agricultural education. Pure local computation — no key, no third-party service, instant. Dates as YYYY-MM-DD. Live, nothing stored. 2 compute endpoints. Averages, not a veterinary prediction.

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

## Pricing
- **Free** (Free) — 6,550 calls/Mo, 2 req/s
- **Starter** ($3/Mo) — 62,500 calls/Mo, 6 req/s
- **Pro** ($9/Mo) — 250,000 calls/Mo, 15 req/s
- **Mega** ($29/Mo) — 1,430,000 calls/Mo, 40 req/s

## Endpoints

### Gestation

#### `GET /v1/gestation` — Due date from breeding

**Parameters:**
- `species` (query, required, string) — cattle, horse, goat, dog, pig, … Example: `cattle`
- `breeding_date` (query, optional, string) — Breeding date YYYY-MM-DD Example: `2026-01-01`
- `target_birth_date` (query, optional, string) — Or target birth date (reverse)
- `gestation_days` (query, optional, string) — Override average days

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/gestation-api/v1/gestation?species=cattle&breeding_date=2026-01-01"
```

**Response:**
```json
{
    "data": {
        "note": "Due date = breeding date + gestation days. The earliest/latest span the normal ± window for the species; individual animals vary.",
        "inputs": {
            "species": "cattle",
            "breeding_date": "2026-01-01"
        },
        "due_date": "2026-10-11",
        "due_weekday": "Sunday",
        "latest_date": "2026-10-16",
        "window_days": 5,
        "earliest_date": "2026-10-06",
        "gestation_days": 283
    },
    "meta": {
        "timestamp": "2026-06-06T07:14:11.665Z",
        "request_id": "c65a2499-d2f4-49ed-afa5-69d13b26498f"
    },
    "status": "ok",
    "message": "Gestation due date",
    "success": true
}
```

#### `GET /v1/incubation` — Hatch date from set date

**Parameters:**
- `species` (query, required, string) — chicken, duck, goose, quail, … Example: `chicken`
- `set_date` (query, required, string) — Set date YYYY-MM-DD Example: `2026-04-01`
- `incubation_days` (query, optional, string) — Override average days

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/gestation-api/v1/incubation?species=chicken&set_date=2026-04-01"
```

**Response:**
```json
{
    "data": {
        "note": "Hatch = set date + incubation days. Lockdown (stop turning, raise humidity) is ~3 days before hatch; candle around day 7 and day 14 to check development.",
        "inputs": {
            "species": "chicken",
            "set_date": "2026-04-01"
        },
        "hatch_date": "2026-04-22",
        "hatch_weekday": "Wednesday",
        "lockdown_date": "2026-04-19",
        "candling_day_7": "2026-04-08",
        "candling_day_14": "2026-04-15",
        "incubation_days": 21
    },
    "meta": {
        "timestamp": "2026-06-06T07:14:11.749Z",
        "request_id": "70f76315-aba4-4edf-8be9-cfc2ce196725"
    },
    "status": "ok",
    "message": "Egg incubation",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Spec + species table

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

**Response:**
```json
{
    "data": {
        "notes": "Dates as YYYY-MM-DD (UTC). Lengths are species averages; pass gestation_days/incubation_days to override. A planning aid, not a veterinary prediction.",
        "service": "gestation-api",
        "endpoints": {
            "GET /v1/meta": "This document (includes species and gestation/incubation lengths).",
            "GET /v1/gestation": "Due date (and ± window) from species + breeding date, or the breeding date for a target birth.",
            "GET /v1/incubation": "Hatch date, lockdown and candling days from a bird species + set date."
        },
        "description": "Animal gestation and egg-incubation maths: due and hatch dates from a breeding or set date for dozens of species.",
        "gestation_days": {
            "cat": 64,
            "cow": 283,
            "dog": 63,
            "ewe": 147,
            "fox": 52,
            "pig": 114,
            "rat": 22,
            "sow": 114,
            "deer": 200,
            "goat": 150,
            "mare": 340,
            "mink": 50,
            "bison": 285,
            "camel": 390,
            "horse": 340,
            "llama": 350,
            "mouse": 19,
            "sheep": 147,
            "alpaca": 345,
            "cattle": 283,
            "donkey": 365,
            "ferret": 42,
            "rabbit": 31,
            "buffalo": 310,
            "hamster": 16,
            "elephant": 640,
            "guinea-pig": 68
        },
        "incubation_days": {
          
…(truncated, see openapi.json for full schema)
```


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