# Hydropower API
> Hydroelectric-power engineering maths as an API, computed locally and deterministically. The power endpoint computes the electrical power a hydro plant generates with P = ρ·g·Q·H·η, from the water flow rate, the net head (the effective drop), the overall turbine-generator efficiency (typically 0.80–0.92) and the water density, returning both the gross power at 100 % efficiency and the net electrical output. The sizing endpoint inverts the relation to size a scheme — given a target power it solves the flow rate needed at a known head, or the head needed at a known flow, Q = P/(ρ·g·H·η). The annual-energy endpoint computes the yearly energy from the rated power and a capacity factor (typically 0.3–0.6 for hydro, accounting for water availability and downtime), E = P × 8760 h × capacity factor, and an optional revenue from an electricity price. Flow is in cubic metres per second, head in metres, efficiency 0–1, power in watts, kilowatts and megawatts. Everything is computed locally and deterministically, so it is instant and private. Ideal for renewable-energy, micro-hydro, civil-engineering, feasibility and sustainability app developers, run-of-river and reservoir tools, and energy education. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is hydroelectric generation; for wind-turbine power use a wind-power API, for solar resource a solar API and for pump (energy-consuming) duty a pump 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/hydropower-api/..."
```

## Pricing
- **Free** (Free) — 2,400 calls/Mo, 2 req/s
- **Starter** ($9/Mo) — 39,000 calls/Mo, 6 req/s
- **Pro** ($25/Mo) — 265,000 calls/Mo, 15 req/s
- **Mega** ($76/Mo) — 1,750,000 calls/Mo, 40 req/s

## Endpoints

### Hydropower

#### `GET /v1/annual-energy` — Annual energy

**Parameters:**
- `power` (query, optional, string) — Rated power (kW) Example: `1667`
- `flow_rate` (query, optional, string) — Or flow (m³/s)
- `head` (query, optional, string) — with head (m)
- `capacity_factor` (query, optional, string) — Capacity factor (0–1) Example: `0.5`
- `electricity_price` (query, optional, string) — Price per kWh Example: `0.10`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/hydropower-api/v1/annual-energy?power=1667&capacity_factor=0.5&electricity_price=0.10"
```

**Response:**
```json
{
    "data": {
        "note": "Annual energy = rated power × 8760 h × capacity factor. The capacity factor (typically 0.3–0.6 for hydro) accounts for water availability and downtime.",
        "inputs": {
            "power_kw": 1667,
            "capacity_factor": 0.5
        },
        "annual_revenue": 730146,
        "full_load_hours": 4380,
        "annual_energy_gwh": 7.30146,
        "annual_energy_kwh": 7301460,
        "annual_energy_mwh": 7301.46,
        "electricity_price": 0.1
    },
    "meta": {
        "timestamp": "2026-06-05T11:30:34.085Z",
        "request_id": "f61a14f7-3fb2-452e-9489-87c6acaf7db6"
    },
    "status": "ok",
    "message": "Annual energy",
    "success": true
}
```

#### `GET /v1/power` — Hydro power

**Parameters:**
- `flow_rate` (query, required, string) — Flow rate (m³/s) Example: `10`
- `head` (query, required, string) — Net head (m) Example: `20`
- `efficiency` (query, optional, string) — Overall efficiency (0–1) Example: `0.85`
- `density` (query, optional, string) — Water density (kg/m³) Example: `1000`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/hydropower-api/v1/power?flow_rate=10&head=20&efficiency=0.85&density=1000"
```

**Response:**
```json
{
    "data": {
        "note": "Hydroelectric power P = ρ·g·Q·H·η. Gross power assumes 100 % efficiency; the net (electrical) power applies the overall turbine-generator efficiency (typically 0.80–0.92).",
        "inputs": {
            "head_m": 20,
            "efficiency": 0.85,
            "density_kg_m3": 1000,
            "flow_rate_m3s": 10
        },
        "power_w": 1667130.5,
        "power_kw": 1667.1305,
        "power_mw": 1.6671305,
        "gross_power_w": 1961330,
        "gross_power_kw": 1961.33
    },
    "meta": {
        "timestamp": "2026-06-05T11:30:34.193Z",
        "request_id": "686a4f5c-c0b8-49fd-b3e8-2eee04debc67"
    },
    "status": "ok",
    "message": "Hydro power",
    "success": true
}
```

#### `GET /v1/sizing` — Flow/head sizing

**Parameters:**
- `target_power` (query, required, string) — Target power (kW) Example: `1667`
- `head` (query, optional, string) — Head (m) to solve flow Example: `20`
- `flow_rate` (query, optional, string) — Or flow (m³/s) to solve head
- `efficiency` (query, optional, string) — Efficiency (0–1) Example: `0.85`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/hydropower-api/v1/sizing?target_power=1667&head=20&efficiency=0.85"
```

**Response:**
```json
{
    "data": {
        "note": "Required flow Q = P / (ρ·g·H·η) to generate the target electrical power at the given head.",
        "inputs": {
            "head_m": 20,
            "efficiency": 0.85,
            "target_power_kw": 1667
        },
        "required_flow_rate_m3s": 9.999217
    },
    "meta": {
        "timestamp": "2026-06-05T11:30:34.276Z",
        "request_id": "ce99182c-7c4c-40c0-83e9-4de28207676a"
    },
    "status": "ok",
    "message": "Flow/head sizing",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "Flow in m³/s, head in m, efficiency 0–1 (default 0.85), density kg/m³ (default 1000), power in W/kW/MW, capacity factor 0–1 (default 0.5).",
        "service": "hydropower-api",
        "formulae": {
            "flow": "Q = P / (ρ·g·H·η)",
            "power": "P = ρ·g·Q·H·η",
            "annual_energy": "E = P × 8760 × capacity_factor"
        },
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/power": "Generated electrical power from flow rate, net head and efficiency.",
            "GET /v1/sizing": "Required flow (or head) to reach a target power.",
            "GET /v1/annual-energy": "Annual energy and optional revenue from power and capacity factor."
        },
        "description": "Hydroelectric power calculator: generated power from flow, head and efficiency; sizing the flow or head for a target power; and annual energy and revenue from the capacity factor."
    },
    "meta": {
        "timestamp": "2026-06-05T11:30:34.378Z",
        "request_id": "8fafd24d-9412-424a-a96a-e7c7e0a1e9f8"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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