# Irrigation Design API
> Irrigation-design maths as an API, computed locally and deterministically — the sprinkler numbers a landscaper, irrigation tech or gardener sizes a system with. The precip-rate endpoint gives the precipitation rate in inches per hour from the flow and spacing: PR = 96.25 × GPM per head ÷ the area each head waters (head spacing × row spacing in feet), where 96.25 is the in/hr one gallon-per-minute makes over a square foot — three-GPM heads on a 15 × 15 ft grid lay down about 1.28 in/hr. The runtime endpoint turns a target water depth into a run-time: depth ÷ precipitation rate, divided by the system efficiency because no system is perfectly even, so applying a half-inch at 1.28 in/hr takes about 23 minutes at full efficiency, longer with real-world uniformity. The zone endpoint sizes a valve zone: maximum heads = available flow ÷ each head's GPM, rounded down so you never starve the line — 13 GPM drives five 2.6-GPM heads with nothing to spare. Everything is computed locally and deterministically, so it is instant and private. Ideal for irrigation and landscaping apps, sprinkler-design and contractor tools, smart-controller schedulers, and garden-planning sites. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 compute endpoints. For evapotranspiration or weather use a weather API; for material volume use a mulch 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/irrigation-api/..."
```

## Pricing
- **Free** (Free) — 500 calls/Mo, 2 req/s
- **Starter** ($5/Mo) — 13,500 calls/Mo, 6 req/s
- **Pro** ($17/Mo) — 85,000 calls/Mo, 15 req/s
- **Mega** ($51/Mo) — 275,000 calls/Mo, 36 req/s

## Endpoints

### Irrigation

#### `GET /v1/precip-rate` — Sprinkler precipitation rate

**Parameters:**
- `gpm_per_head` (query, required, string) — Flow per head in GPM Example: `3`
- `head_spacing_ft` (query, required, string) — Head spacing in feet Example: `15`
- `row_spacing_ft` (query, optional, string) — Row spacing in feet (default = head spacing) Example: `15`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/irrigation-api/v1/precip-rate?gpm_per_head=3&head_spacing_ft=15&row_spacing_ft=15"
```

**Response:**
```json
{
    "data": {
        "note": "Precipitation rate = 96.25 × GPM per head ÷ the area each head waters (head spacing × row spacing in feet). 96.25 is the in/hr that one gallon-per-minute makes over a square foot. Match precipitation rates within a zone — mixing rates means some areas drown while others go dry.",
        "inputs": {
            "gpm_per_head": 3,
            "row_spacing_ft": 15,
            "head_spacing_ft": 15
        },
        "precip_rate_in_hr": 1.283,
        "area_per_head_sqft": 225
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:44.136Z",
        "request_id": "7b9c4f96-5e0c-4f27-8208-ff0336eed490"
    },
    "status": "ok",
    "message": "Precipitation rate",
    "success": true
}
```

#### `GET /v1/runtime` — Run-time to apply a depth

**Parameters:**
- `water_depth_in` (query, required, string) — Target water depth in inches Example: `0.5`
- `precip_rate_in_hr` (query, required, string) — Precipitation rate in in/hr Example: `1.28`
- `efficiency_pct` (query, optional, string) — System efficiency % (default 75) Example: `75`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/irrigation-api/v1/runtime?water_depth_in=0.5&precip_rate_in_hr=1.28&efficiency_pct=75"
```

**Response:**
```json
{
    "data": {
        "note": "Run-time = depth to apply ÷ precipitation rate, then divided by the system efficiency (distribution uniformity) because no system is perfectly even — 75 % is typical for spray, higher for drip. Split long run-times into cycles (cycle-and-soak) on slopes or clay so water soaks in instead of running off.",
        "inputs": {
            "efficiency_pct": 75,
            "water_depth_in": 0.5,
            "precip_rate_in_hr": 1.28
        },
        "base_minutes": 23.4,
        "adjusted_minutes": 31.3
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:44.220Z",
        "request_id": "5bede589-9705-4e61-b69c-949ac57532b3"
    },
    "status": "ok",
    "message": "Run-time",
    "success": true
}
```

#### `GET /v1/zone` — Maximum heads per zone

**Parameters:**
- `available_gpm` (query, required, string) — Available flow in GPM Example: `13`
- `gpm_per_head` (query, required, string) — Flow per head in GPM Example: `2.6`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/irrigation-api/v1/zone?available_gpm=13&gpm_per_head=2.6"
```

**Response:**
```json
{
    "data": {
        "note": "Max heads per zone = available flow ÷ each head's GPM, rounded down — never exceed the supply or every head loses pressure and throw. Find available GPM from your service pipe size and pressure, and leave a margin. For drip, total emitter GPH must likewise stay under the zone's capacity.",
        "inputs": {
            "gpm_per_head": 2.6,
            "available_gpm": 13
        },
        "used_gpm": 13,
        "max_heads": 5,
        "spare_gpm": 0
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:44.307Z",
        "request_id": "572b3c5f-9f74-4cf3-9b4f-e3779ce91279"
    },
    "status": "ok",
    "message": "Zone heads",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "US units (GPM, feet, inches). PR = 96.25 × GPM ÷ area; run-time = depth ÷ PR ÷ efficiency; max heads = available GPM ÷ per-head GPM. Estimates — verify pressure and uniformity on site.",
        "service": "irrigation-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/zone": "Maximum sprinkler heads a zone's available flow can drive.",
            "GET /v1/runtime": "Run-time (minutes) to apply a water depth at a precipitation rate.",
            "GET /v1/precip-rate": "Precipitation rate (in/hr) from GPM per head and head/row spacing."
        },
        "description": "Irrigation-design maths: sprinkler precipitation rate, run-time to apply a depth, and the maximum heads a zone's flow can drive."
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:44.402Z",
        "request_id": "fe4d28c2-7fd5-4c71-bfef-412363a333da"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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