# Stormwater Runoff API
> Stormwater-runoff civil-engineering maths as an API, computed locally and deterministically. The rational endpoint computes the peak runoff from a catchment with the Rational Method, Q = C·i·A — in metric form Q(m³/s) = C·i·A/360 with rainfall intensity i in mm/h and area A in hectares, or in US form Q(cfs) = C·i·A with intensity in in/h and area in acres — where the runoff coefficient C is the fraction of rain that runs off (about 0.9 for paving and 0.2 for lawns). The time-of-concentration endpoint computes how long water takes to flow from the most remote point of the catchment to the outlet with the Kirpich formula, tc = 0.0195·L^0.77·S^(−0.385) minutes, from the flow-path length and slope; this sets the design-storm duration. The detention endpoint gives a first-order estimate of the detention-pond storage needed to throttle a peak inflow down to an allowable outflow over a storm duration, (Q_in − Q_out)·duration. Coefficients are dimensionless, intensities in mm/h or in/h, areas in ha or acres, lengths in m and flows in m³/s. Everything is computed locally and deterministically, so it is instant and private. Ideal for civil-engineering, drainage, urban-planning, landscape and flood-risk app developers, sewer-sizing and detention tools, and hydrology education. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is stormwater runoff; for open-channel flow use a Manning API and for pipe friction a Darcy 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/runoff-api/..."
```

## Pricing
- **Free** (Free) — 2,480 calls/Mo, 2 req/s
- **Starter** ($9/Mo) — 38,000 calls/Mo, 6 req/s
- **Pro** ($24/Mo) — 244,000 calls/Mo, 15 req/s
- **Mega** ($73/Mo) — 1,650,000 calls/Mo, 40 req/s

## Endpoints

### Runoff

#### `GET /v1/detention` — Detention storage

**Parameters:**
- `inflow_peak` (query, required, string) — Peak inflow (m³/s) Example: `0.5`
- `allowable_outflow` (query, required, string) — Allowable outflow (m³/s) Example: `0.2`
- `duration` (query, required, string) — Storm duration (min) Example: `30`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/runoff-api/v1/detention?inflow_peak=0.5&allowable_outflow=0.2&duration=30"
```

**Response:**
```json
{
    "data": {
        "note": "First-order detention storage = (Q_in − Q_out) × duration, treating the excess as a constant rate over the storm. Use a routed hydrograph for design; this is a quick upper-bound estimate.",
        "inputs": {
            "duration_min": 30,
            "inflow_peak_m3s": 0.5,
            "allowable_outflow_m3s": 0.2
        },
        "required_storage_m3": 540,
        "required_storage_liters": 540000
    },
    "meta": {
        "timestamp": "2026-06-05T11:30:26.137Z",
        "request_id": "29362af1-0a48-467c-a6d3-2e41ba644439"
    },
    "status": "ok",
    "message": "Detention storage",
    "success": true
}
```

#### `GET /v1/rational` — Rational method

**Parameters:**
- `runoff_coefficient` (query, required, string) — Runoff coefficient C (0–1) Example: `0.5`
- `intensity` (query, required, string) — Rainfall intensity (mm/h or in/h) Example: `50`
- `area` (query, required, string) — Catchment area (ha or acres) Example: `2`
- `units` (query, optional, string) — metric or us Example: `metric`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/runoff-api/v1/rational?runoff_coefficient=0.5&intensity=50&area=2&units=metric"
```

**Response:**
```json
{
    "data": {
        "note": "Metric Rational Method: Q(m³/s) = C·i·A / 360, with rainfall intensity i in mm/h and catchment area A in hectares. C is the impervious-fraction runoff coefficient.",
        "inputs": {
            "units": "metric",
            "area_ha": 2,
            "intensity_mm_h": 50,
            "runoff_coefficient": 0.5
        },
        "peak_flow_l_s": 138.88889,
        "peak_flow_m3s": 0.13888889
    },
    "meta": {
        "timestamp": "2026-06-05T11:30:26.261Z",
        "request_id": "32fca715-a80d-46a3-9b43-c5f39be5b464"
    },
    "status": "ok",
    "message": "Rational method",
    "success": true
}
```

#### `GET /v1/time-of-concentration` — Time of concentration

**Parameters:**
- `length` (query, required, string) — Flow-path length (m) Example: `300`
- `slope` (query, required, string) — Slope (m/m) Example: `0.02`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/runoff-api/v1/time-of-concentration?length=300&slope=0.02"
```

**Response:**
```json
{
    "data": {
        "note": "Kirpich (1940): tc = 0.0195·L^0.77·S^(−0.385) minutes (L in m, S the channel slope). The time of concentration sets the design-storm duration in the Rational Method.",
        "inputs": {
            "slope": 0.02,
            "length_m": 300
        },
        "time_of_concentration_s": 426.26,
        "time_of_concentration_min": 7.1043
    },
    "meta": {
        "timestamp": "2026-06-05T11:30:26.347Z",
        "request_id": "7cc0bee9-b352-4c15-b194-cf3b47319949"
    },
    "status": "ok",
    "message": "Time of concentration",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "Runoff coefficient C is 0–1 (0.9 paved, 0.2 lawns). units: metric (mm/h, ha) or us (in/h, acres). Slope is m/m, length m, flows m³/s.",
        "service": "runoff-api",
        "formulae": {
            "kirpich": "tc(min) = 0.0195·L^0.77·S^(−0.385)",
            "rational_us": "Q(cfs) = C·i·A (i in/h, A acres)",
            "rational_metric": "Q(m³/s) = C·i·A/360 (i mm/h, A ha)"
        },
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/rational": "Peak runoff Q = C·i·A (metric or US units).",
            "GET /v1/detention": "Required detention storage from inflow peak, allowable outflow and duration.",
            "GET /v1/time-of-concentration": "Kirpich time of concentration from flow-path length and slope."
        },
        "description": "Stormwater-runoff calculator: peak runoff by the Rational Method, the time of concentration (Kirpich) and a first-order detention-storage estimate."
    },
    "meta": {
        "timestamp": "2026-06-05T11:30:26.447Z",
        "request_id": "e01ccc92-afa7-4748-9296-9b5dabab140a"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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