# USGS Streamflow API
> Live river and stream conditions from the USGS Water Services network. The catalogue of 16,900+ active US streamflow gauges is searchable by name, state or coordinate; the live endpoint returns the latest observation for any gauge: streamflow / discharge (in cubic feet per second and m³/s) and gauge height (in feet and metres), with the station name, observation time and coordinates. Find the gauges nearest any lat/lon. Ideal for flood monitoring, hydrology, whitewater/fishing & recreation apps, drought tracking and environmental dashboards.

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

## Pricing
- **Free** (Free) — 3,000 calls/Mo, 2 req/s
- **Starter** ($6/Mo) — 40,000 calls/Mo, 8 req/s
- **Pro** ($18/Mo) — 220,000 calls/Mo, 20 req/s
- **Mega** ($47/Mo) — 1,100,000 calls/Mo, 50 req/s

## Endpoints

### Streamflow

#### `GET /v1/gauge` — Latest live observation for a USGS gauge

**Parameters:**
- `site` (query, required, string) — USGS site number, e.g. 01646500 (Potomac River) Example: `01646500`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/streamflow-api/v1/gauge?site=01646500"
```

**Response:**
```json
{
    "data": {
        "name": "POTOMAC RIVER NEAR WASH, DC LITTLE FALLS PUMP STA",
        "site": "01646500",
        "state": "MD",
        "source": "USGS Water Services",
        "latitude": 38.94977778,
        "longitude": -77.12763889,
        "observed_at": "2026-05-31T01:50:00.000-04:00",
        "gauge_height_m": 1.64,
        "streamflow_cfs": 25900,
        "streamflow_m3s": 733.405,
        "gauge_height_ft": 5.38
    },
    "meta": {
        "timestamp": "2026-05-31T06:28:06.661Z",
        "request_id": "0ec9e7ad-b933-497a-9711-4e9a51fe5ae4"
    },
    "status": "ok",
    "message": "Gauge observation retrieved",
    "success": true
}
```

#### `GET /v1/nearby` — Gauges within a radius of a coordinate

**Parameters:**
- `lat` (query, optional, string) — Latitude (-90..90) Example: `38.9`
- `lon` (query, optional, string) — Longitude (-180..180) Example: `-77.0`
- `radius_km` (query, optional, string) — Search radius in km (1-5000, default 100)
- `limit` (query, optional, string) — Max results (1-100, default 10)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/streamflow-api/v1/nearby?lat=38.9&lon=-77.0"
```

**Response:**
```json
{
    "data": {
        "count": 10,
        "total": 245,
        "center": {
            "lat": 38.9,
            "lon": -77
        },
        "results": [
            {
                "name": "HICKEY RUN AT NATIONAL ARBORETUM AT WASHINGTON, DC",
                "site": "01651770",
                "state": "DC",
                "latitude": 38.91611,
                "longitude": -76.96886,
                "distance_km": 3.2
            },
            {
                "name": "ANACOSTIA RIVER AT ANACOSTIA PARK BOAT RAMP, DC",
                "site": "01651812",
                "state": "DC",
                "latitude": 38.87992,
                "longitude": -76.97083,
                "distance_km": 3.4
            },
            {
                "name": "ANACOSTIA RIVER AT KENILWORTH AT WASHINGTON, DC",
                "site": "01651760",
                "state": "DC",
                "latitude": 38.90917,
                "longitude": -76.95528,
                "distance_km": 4
            },
            {
                "name": "Anacostia River nr Buzzard Point at Washington, DC",
                "site": "01651827",
                "state": "DC",
                "latitude": 38.86517,
                "longitude": -77.01033,
                "distance_km": 4
            },
            {
                "name": "WATTS BRANCH AT WASHINGTON, DC",
                "site": "01651800",
                "state": "DC",
                "latitude": 38.90128,
                "longitude
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/search` — Search the gauge catalogue

**Parameters:**
- `q` (query, optional, string) — Name search, e.g. potomac Example: `potomac`
- `state` (query, optional, string) — 2-letter US state, e.g. CO
- `limit` (query, optional, string) — Results per page (1-100, default 20) Example: `20`
- `offset` (query, optional, string) — Pagination offset Example: `0`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/streamflow-api/v1/search?q=potomac&limit=20&offset=0"
```

**Response:**
```json
{
    "data": {
        "count": 20,
        "limit": 20,
        "query": "potomac",
        "state": null,
        "total": 22,
        "offset": 0,
        "results": [
            {
                "name": "NORTH BRANCH POTOMAC RIVER AT STEYER, MD",
                "site": "01595000",
                "state": "MD",
                "latitude": 39.30189,
                "longitude": -79.30689
            },
            {
                "name": "NORTH BRANCH POTOMAC RIVER AT KITZMILLER, MD",
                "site": "01595500",
                "state": "MD",
                "latitude": 39.39389,
                "longitude": -79.18169
            },
            {
                "name": "NORTH BRANCH POTOMAC RIVER AT LUKE, MD",
                "site": "01598500",
                "state": "MD",
                "latitude": 39.47897,
                "longitude": -79.06378
            },
            {
                "name": "NORTH BRANCH POTOMAC RIVER NEAR CUMBERLAND, MD",
                "site": "01603000",
                "state": "MD",
                "latitude": 39.62181,
                "longitude": -78.77342
            },
            {
                "name": "POTOMAC RIVER AT PAW PAW, WV",
                "site": "01610000",
                "state": "MD",
                "latitude": 39.53886,
                "longitude": -78.45561
            },
            {
                "name": "POTOMAC RIVER AT HANCOCK, MD",
                "site": "01613000",
                "stat
…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Totals & source

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

**Response:**
```json
{
    "data": {
        "note": "Active US streamflow gauges. /v1/gauge fetches the latest live discharge (cfs) and gauge height (ft) from USGS; catalogue is bundled.",
        "sites": 16938,
        "fields": [
            "site",
            "name",
            "state",
            "observed_at",
            "streamflow_cfs",
            "streamflow_m3s",
            "gauge_height_ft",
            "gauge_height_m",
            "latitude",
            "longitude"
        ],
        "source": "USGS Water Services (waterservices.usgs.gov)",
        "endpoints": [
            "/v1/gauge",
            "/v1/search",
            "/v1/nearby",
            "/v1/meta"
        ]
    },
    "meta": {
        "timestamp": "2026-05-31T06:28:06.848Z",
        "request_id": "838b1e8c-c19f-4c1c-b0e0-c97b6b2a7c21"
    },
    "status": "ok",
    "message": "Meta retrieved",
    "success": true
}
```


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