# Rainwater Harvesting API
> Rainwater-harvesting maths as an API, computed locally and deterministically. The harvest endpoint works out how much water a roof collects from a given rainfall — from the catchment (roof plan) area, the rainfall depth and a runoff coefficient it returns the harvested volume in litres, US and UK gallons and cubic metres, using the identity that 1 mm of rain over 1 m² collects 1 litre before losses. The runoff coefficient can be given directly or looked up from the roof type (smooth metal collects the most at ~0.9, green roofs the least at ~0.3). The demand endpoint sizes a storage tank from a daily demand (given directly or as people × litres per person) and the length of the dry spell you want to cover, and — if you also pass the annual rainfall and roof area — checks whether a year of harvest can meet a year of demand. The firstflush endpoint sizes a first-flush diverter, the volume of dirty initial rain to discard. Areas accept square metres or square feet (or length × width), rainfall accepts millimetres, centimetres or inches. Everything is computed locally and deterministically, so it is instant and private. Ideal for sustainability and off-grid apps, plumbing and landscaping tools, smart-home water systems, and construction planners. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 4 endpoints. This is rainwater catchment maths; for roof pitch and area geometry use a roofing API and for general construction material quantities use a construction 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/rainwater-api/..."
```

## Pricing
- **Free** (Free) — 12,835 calls/Mo, 2 req/s
- **Starter** ($14/Mo) — 22,450 calls/Mo, 8 req/s
- **Pro** ($34/Mo) — 274,500 calls/Mo, 20 req/s
- **Mega** ($72/Mo) — 1,415,000 calls/Mo, 50 req/s

## Endpoints

### Rainwater

#### `GET /v1/demand` — Storage tank sizing

**Parameters:**
- `daily_demand_litres` (query, optional, string) — Daily demand (or people) Example: `150`
- `people` (query, optional, string) — People in household
- `litres_per_person` (query, optional, string) — Per-person l/day (default 150)
- `dry_days` (query, required, string) — Dry spell to cover (days) Example: `30`
- `annual_rainfall_mm` (query, optional, string) — For yearly supply check
- `area` (query, optional, string) — Roof area (for supply check)
- `roof_type` (query, optional, string) — Roof type (for supply check)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/rainwater-api/v1/demand?daily_demand_litres=150&dry_days=30"
```

**Response:**
```json
{
    "data": {
        "note": "Required storage = daily demand × dry days. Supply check (if annual_rainfall_mm + area given) compares yearly harvest to yearly demand.",
        "dry_days": 30,
        "required_storage": {
            "litres": 4500,
            "uk_gallons": 989.9,
            "us_gallons": 1188.8,
            "cubic_metres": 4.5
        },
        "daily_demand_litres": 150
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:11.949Z",
        "request_id": "4115c221-92e3-4288-8921-0810e482d07a"
    },
    "status": "ok",
    "message": "Storage tank sizing from demand and a dry spell",
    "success": true
}
```

#### `GET /v1/firstflush` — First-flush diverter volume

**Parameters:**
- `area` (query, optional, string) — Catchment area (or length+width) Example: `80`
- `length` (query, optional, string) — Roof length
- `width` (query, optional, string) — Roof width
- `area_unit` (query, optional, string) — m2|ft2 Example: `m2`
- `flush_mm` (query, optional, string) — Discard depth (default 0.5 mm) Example: `0.5`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/rainwater-api/v1/firstflush?area=80&area_unit=m2&flush_mm=0.5"
```

**Response:**
```json
{
    "data": {
        "note": "First-flush diverter discards the dirty first ~0.5–2 mm of rain. Volume = area(m²) × flush(mm).",
        "flush_mm": 0.5,
        "diverter_volume": {
            "litres": 40,
            "uk_gallons": 8.8,
            "us_gallons": 10.6,
            "cubic_metres": 0.04
        },
        "catchment_area_m2": 80
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:12.018Z",
        "request_id": "a2d3cea7-ef25-4d88-b0b2-afff2006122d"
    },
    "status": "ok",
    "message": "First-flush diverter volume",
    "success": true
}
```

#### `GET /v1/harvest` — Collected volume from roof + rainfall

**Parameters:**
- `area` (query, optional, string) — Catchment area (or length+width) Example: `100`
- `length` (query, optional, string) — Roof length
- `width` (query, optional, string) — Roof width
- `area_unit` (query, optional, string) — m2|ft2 (or m|ft for L×W) Example: `m2`
- `rainfall` (query, required, string) — Rainfall depth Example: `25`
- `rainfall_unit` (query, optional, string) — mm|cm|in Example: `mm`
- `roof_type` (query, optional, string) — metal|concrete|clay_tile|asphalt_shingle|green_roof|… Example: `metal`
- `runoff_coefficient` (query, optional, string) — Or explicit 0-1

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/rainwater-api/v1/harvest?area=100&area_unit=m2&rainfall=25&rainfall_unit=mm&roof_type=metal"
```

**Response:**
```json
{
    "data": {
        "note": "Collected ≈ area(m²) × rainfall(mm) × runoff coefficient. 1 mm over 1 m² = 1 litre before losses.",
        "collected": {
            "litres": 2250,
            "uk_gallons": 494.9,
            "us_gallons": 594.4,
            "cubic_metres": 2.25
        },
        "rainfall_mm": 25,
        "catchment_area_m2": 100,
        "coefficient_source": "metal",
        "runoff_coefficient": 0.9
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:12.109Z",
        "request_id": "8d78cd32-d94c-4be5-b5bd-468b2b935bc2"
    },
    "status": "ok",
    "message": "Collected volume from roof area and rainfall",
    "success": true
}
```

#### `GET /v1/rooftypes` — Runoff coefficient reference

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

**Response:**
```json
{
    "data": {
        "note": "Runoff (collection) coefficients are typical values; smooth metal roofs collect the most, green roofs the least.",
        "roof_types": {
            "metal": 0.9,
            "gravel": 0.7,
            "concrete": 0.8,
            "clay_tile": 0.8,
            "green_roof": 0.3,
            "glazed_tile": 0.85,
            "concrete_tile": 0.8,
            "asphalt_shingle": 0.85
        },
        "default_coefficient": 0.85
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:12.201Z",
        "request_id": "eaa13d47-233c-440b-a26e-4b2ed57b92f2"
    },
    "status": "ok",
    "message": "Runoff coefficient reference",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "api": "rainwater",
        "note": "Rainwater harvesting maths — computed locally and deterministically, no key, no third-party service.",
        "constants": {
            "MM_PER_IN": 25.4,
            "M2_PER_FT2": 0.09290304,
            "L_PER_UKGAL": 4.54609,
            "L_PER_USGAL": 3.785411784
        },
        "endpoints": [
            "/v1/harvest",
            "/v1/demand",
            "/v1/firstflush",
            "/v1/rooftypes",
            "/v1/meta"
        ]
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:12.271Z",
        "request_id": "11557ca3-8264-4bda-b6a0-96fd753d7585"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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