Where do the readings come from?

The USGS Water Data service, fetched live and edge-cached for 15 minutes: streamflow discharge in cubic feet per second, gage height in feet and water temperature in Celsius, each with its timestamp.

Which gauges are covered?

11,605 active USGS streamgages across all 50 states, DC and Puerto Rico, in a searchable directory with nearest-by-coordinate lookup.

What if a gauge stops reporting?

Every reading carries its timestamp and a stale flag, so your code can tell a current value from one that is hours old.

Can I query several sites at once?

Yes. The conditions endpoint accepts up to 10 site ids in one call.

Does it include forecasts or flood stages?

No. It serves observed conditions. Flood stage thresholds come from the National Weather Service and are not part of this dataset.

DataMAINTAINED2 tokens / call

River Conditions API

Live streamflow, gage height and water temperature from 11,605 USGS river gauges, with nearest-gauge lookup

Live river conditions from every active USGS stream gauge. A searchable directory of 11,605 active US streamgages (all 50 states, DC and Puerto Rico) with nearest-gauge lookup by coordinates — and live readings fetched straight from the USGS instantaneous-values service and edge-cached 15 minutes: streamflow discharge (ft³/s), gage height (ft) and water temperature (°C). The Colorado at Lees Ferry right now: 7,740 cfs, 7.95 ft, 20.2 °C, timestamped. Ask for up to 10 sites in one call, one site's detail, or the nearest gauges to a point with their conditions inline (Boulder CO → Fourmile Creek at Orodell, 4.9 km). Every reading carries its own timestamp and a stale flag when a sensor has gone quiet for 24+ hours — a discontinued temperature series never masquerades as current. Fishing and kayaking apps, flood awareness, irrigation tools, hydro dashboards and outdoor trip planners — the same data behind every river-levels site, from the primary source. US coverage (USGS network).

Every call needs an X-Api-Key header. A free key includes 500 tokens a month, no card required. 2 tokens per call, so the free plan covers about 250 calls a month.

Start free — 500 tokens / mo →See all plans

No credit card requiredAccess to 125+ APIsCancel anytime

response.json

{
  "ok": true,
  "site": {
    "id": "09380000",
    "name": "COLORADO RIVER AT LEES FERRY, AZ",
    "state": "AZ",
    "lat": 36.86433,
    "lng": -111.58787,
    "huc": "140700061105"
  },
  "units": {
    "discharge_cfs": "ft3/s",
    "gage_height_ft": "ft",
    "water_temp_c": "degC"
  },
  "conditions": {
    "gage_height_ft": {
      "value": 8.3,
      "time": "2026-09-13T03:00:00+00:00",
      "stale": false
    },
    "discharge_cfs": {
      "value": 8740,
      "time": "2026-09-13T03:00:00+00:00",
      "stale": false
    },
    "water_temp_c": {
      "value": 21.8,
      "time": "2026-09-13T03:00:00+00:00",
      "stale": false
    }
  }
}

Production Ready: Battle-tested infrastructure with a 99.9% uptime SLA. Rate limits are generous, responses are consistent.
Simple Integration: Standard REST + JSON. Works with any HTTP client. Copy-ready code snippets in 4 languages.
One Key, 125+ APIs: Your DataAndAPIs subscription unlocks every API on the platform — anime, finance, sports, and more.

Use cases for River Conditions API

Show current river conditions near a user for fishing, paddling or flood awareness.
Monitor gauges upstream of a facility and alert when discharge or stage crosses a threshold.
Find the nearest active gauge to any coordinate and link to its USGS page.
Chart multiple sites in one request for a regional water dashboard.

River Conditions API endpoints

Every endpoint with its parameters and a real example response.

OpenAPI definition Postman workspace

GETData Sources
GETGauge Detail
GETLive Conditions
GETNearest Gauges
GETSearch Gauges

GETData Sources

https://api-rivers.dataandapis.com/v1/sources

This endpoint takes no parameters.

Example request

curl "https://api-rivers.dataandapis.com/v1/sources" \
  -H "X-Api-Key: YOUR_API_KEY"

Example response

{
  "ok": true,
  "sources": [
    {
      "slug": "usgs-nwis",
      "name": "USGS National Water Information System",
      "publisher": "US Geological Survey",
      "licence": "US government work (public domain)",
      "source_url": "https://waterdata.usgs.gov/",
      "file_url": "https://waterservices.usgs.gov/",
      "cadence": "site list ~static; readings fetched live",
      "record_count": 11605,
      "retrieved_at": "2026-09-06"
    }
  ]
}

GETGauge Detail

https://api-rivers.dataandapis.com/v1/rivers/sites/{id}

Path parameters

Parameter	Example
id	09380000	Required

Example request

curl "https://api-rivers.dataandapis.com/v1/rivers/sites/09380000" \
  -H "X-Api-Key: YOUR_API_KEY"

Example response

{
  "ok": true,
  "site": {
    "id": "09380000",
    "name": "COLORADO RIVER AT LEES FERRY, AZ",
    "state": "AZ",
    "lat": 36.86433,
    "lng": -111.58787,
    "huc": "140700061105"
  },
  "units": {
    "discharge_cfs": "ft3/s",
    "gage_height_ft": "ft",
    "water_temp_c": "degC"
  },
  "conditions": {
    "gage_height_ft": {
      "value": 8.3,
      "time": "2026-09-13T03:00:00+00:00",
      "stale": false
    },
    "discharge_cfs": {
      "value": 8740,
      "time": "2026-09-13T03:00:00+00:00",
      "stale": false
    },
    "water_temp_c": {
      "value": 21.8,
…

Show full response

{
  "ok": true,
  "site": {
    "id": "09380000",
    "name": "COLORADO RIVER AT LEES FERRY, AZ",
    "state": "AZ",
    "lat": 36.86433,
    "lng": -111.58787,
    "huc": "140700061105"
  },
  "units": {
    "discharge_cfs": "ft3/s",
    "gage_height_ft": "ft",
    "water_temp_c": "degC"
  },
  "conditions": {
    "gage_height_ft": {
      "value": 8.3,
      "time": "2026-09-13T03:00:00+00:00",
      "stale": false
    },
    "discharge_cfs": {
      "value": 8740,
      "time": "2026-09-13T03:00:00+00:00",
      "stale": false
    },
    "water_temp_c": {
      "value": 21.8,
      "time": "2026-09-13T03:00:00+00:00",
      "stale": false
    }
  }
}

GETLive Conditions

https://api-rivers.dataandapis.com/v1/rivers/conditions

Query parameters

Parameter	Example
sites	01646500,09380000	Required

Example request

curl "https://api-rivers.dataandapis.com/v1/rivers/conditions?sites=01646500%2C09380000" \
  -H "X-Api-Key: YOUR_API_KEY"

Example response

{
  "ok": true,
  "units": {
    "discharge_cfs": "ft3/s",
    "gage_height_ft": "ft",
    "water_temp_c": "degC"
  },
  "cache": "readings edge-cached 15 minutes; stale=true means older than 24h",
  "sites": [
    {
      "id": "01646500",
      "name": "POTOMAC RIVER NEAR WASH, DC LITTLE FALLS PUMP STA",
      "state": "MD",
      "lat": 38.94978,
      "lng": -77.12764,
      "huc": "020700081005",
      "conditions": {
        "water_temp_c": {
          "value": 26.6,
          "time": "2026-09-13T03:50:00+00:00",
          "stale": false
        },
        "discharge_cfs": {
          "value": 1940,
          "time": "2026-09-13T03:50:00+00:00",
          "stale": false
        },
        "gage_height_ft": {
…

Show full response

{
  "ok": true,
  "units": {
    "discharge_cfs": "ft3/s",
    "gage_height_ft": "ft",
    "water_temp_c": "degC"
  },
  "cache": "readings edge-cached 15 minutes; stale=true means older than 24h",
  "sites": [
    {
      "id": "01646500",
      "name": "POTOMAC RIVER NEAR WASH, DC LITTLE FALLS PUMP STA",
      "state": "MD",
      "lat": 38.94978,
      "lng": -77.12764,
      "huc": "020700081005",
      "conditions": {
        "water_temp_c": {
          "value": 26.6,
          "time": "2026-09-13T03:50:00+00:00",
          "stale": false
        },
        "discharge_cfs": {
          "value": 1940,
          "time": "2026-09-13T03:50:00+00:00",
          "stale": false
        },
        "gage_height_ft": {
          "value": 2.81,
          "time": "2026-09-13T03:50:00+00:00",
          "stale": false
        }
      }
    },
    {
      "id": "09380000",
      "name": "COLORADO RIVER AT LEES FERRY, AZ",
      "state": "AZ",
      "lat": 36.86433,
      "lng": -111.58787,
      "huc": "140700061105",
      "conditions": {
        "gage_height_ft": {
          "value": 8.3,
          "time": "2026-09-13T03:00:00+00:00",
          "stale": false
        },
        "discharge_cfs": {
          "value": 8740,
          "time": "2026-09-13T03:00:00+00:00",
          "stale": false
        },
        "water_temp_c": {
          "value": 21.8,
          "time": "2026-09-13T03:00:00+00:00",
          "stale": false
        }
      }
    }
  ]
}

GETNearest Gauges

https://api-rivers.dataandapis.com/v1/rivers/nearest

Query parameters

Parameter	Example
lat	40.01	Required
limit	5	Optional
lng	-105.27	Required

Example request

curl "https://api-rivers.dataandapis.com/v1/rivers/nearest?lat=40.01&limit=5&lng=-105.27" \
  -H "X-Api-Key: YOUR_API_KEY"

Example response

{
  "ok": true,
  "query": {
    "lat": 40.01,
    "lng": -105.27
  },
  "sites": [
    {
      "id": "06727500",
      "name": "FOURMILE CREEK AT ORODELL, CO",
      "state": "CO",
      "lat": 40.01867,
      "lng": -105.32625,
      "huc": "10190005",
      "distance_km": 4.9,
      "conditions": {
        "discharge_cfs": {
          "value": 0.01,
          "time": "2026-09-13T03:50:00+00:00",
          "stale": false
        },
        "gage_height_ft": {
          "value": 4.09,
          "time": "2026-09-13T03:50:00+00:00",
          "stale": false
        }
      }
    },
…

Show full response

{
  "ok": true,
  "query": {
    "lat": 40.01,
    "lng": -105.27
  },
  "sites": [
    {
      "id": "06727500",
      "name": "FOURMILE CREEK AT ORODELL, CO",
      "state": "CO",
      "lat": 40.01867,
      "lng": -105.32625,
      "huc": "10190005",
      "distance_km": 4.9,
      "conditions": {
        "discharge_cfs": {
          "value": 0.01,
          "time": "2026-09-13T03:50:00+00:00",
          "stale": false
        },
        "gage_height_ft": {
          "value": 4.09,
          "time": "2026-09-13T03:50:00+00:00",
          "stale": false
        }
      }
    },
    {
      "id": "06730160",
      "name": "FOURMILE CANYON CREEK NEAR SUNSHINE, CO",
      "state": "CO",
      "lat": 40.05761,
      "lng": -105.34878,
      "huc": "10190005",
      "distance_km": 8.5,
      "conditions": {
        "gage_height_ft": {
          "value": 0.56,
          "time": "2026-09-13T03:50:00+00:00",
          "stale": false
        },
        "discharge_cfs": {
          "value": 0,
          "time": "2026-09-13T03:50:00+00:00",
          "stale": false
        }
      }
    },
    {
      "id": "06727410",
      "name": "FOURMILE CREEK AT LOGAN MILL ROAD NEAR CRISMAN, CO",
      "state": "CO",
      "lat": 40.04203,
      "lng": -105.36492,
      "huc": "101900050403",
      "distance_km": 8.8,
      "conditions": {
        "gage_height_ft": {
          "value": 9.07,
          "time": "2026-09-13T03:55:00+00:00",
          "stale": false
        },
        "discharge_cfs": {
          "value": 0.15,
          "time": "2026-09-13T03:55:00+00:00",
          "stale": false
        }
      }
    },
    {
      "id": "06730200",
      "name": "BOULDER CREEK AT NORTH 75TH ST. NEAR BOULDER, CO",
      "state": "CO",
      "lat": 40.05167,
      "lng": -105.17833,
      "huc": "101900050601",
      "distance_km": 9.1,
      "conditions": {
        "gage_height_ft": {
          "value": 4.58,
          "time": "2026-09-13T03:15:00+00:00",
          "stale": false
        },
        "discharge_cfs": {
          "value": 29.6,
          "time": "2026-09-13T03:15:00+00:00",
          "stale": false
        }
      }
    },
    {
      "id": "06729470",
      "name": "SOUTH BOULDER CR AT FOREBAY NR ELDORADO SPRINGS CO",
      "state": "CO",
      "lat": 39.93244,
      "lng": -105.30867,
      "huc": "10190005",
      "distance_km": 9.2,
      "conditions": {
        "water_temp_c": {
          "value": 14.6,
          "time": "2026-09-13T03:00:00+00:00",
          "stale": false
        }
      }
    }
  ]
}

GETSearch Gauges

https://api-rivers.dataandapis.com/v1/rivers/sites

Query parameters

Parameter	Example
q	potomac	Optional
state		Optional

Example request

curl "https://api-rivers.dataandapis.com/v1/rivers/sites?q=potomac" \
  -H "X-Api-Key: YOUR_API_KEY"

Example response

{
  "ok": true,
  "page": 1,
  "limit": 25,
  "total": 21,
  "total_pages": 1,
  "sites": [
    {
      "id": "01606000",
      "name": "N F SOUTH BRANCH POTOMAC RIVER AT CABINS, WV",
      "state": "WV",
      "lat": 38.98455,
      "lng": -79.23365,
      "huc": "02070001"
    },
    {
      "id": "01595800",
      "name": "NORTH BRANCH POTOMAC RIVER AT BARNUM, WV",
      "state": "WV",
      "lat": 39.44511,
      "lng": -79.11081,
      "huc": "020700020207"
    },
    {
      "id": "01595500",
      "name": "NORTH BRANCH POTOMAC RIVER AT KITZMILLER, MD",
      "state": "MD",
      "lat": 39.39389,
…

Show full response

{
  "ok": true,
  "page": 1,
  "limit": 25,
  "total": 21,
  "total_pages": 1,
  "sites": [
    {
      "id": "01606000",
      "name": "N F SOUTH BRANCH POTOMAC RIVER AT CABINS, WV",
      "state": "WV",
      "lat": 38.98455,
      "lng": -79.23365,
      "huc": "02070001"
    },
    {
      "id": "01595800",
      "name": "NORTH BRANCH POTOMAC RIVER AT BARNUM, WV",
      "state": "WV",
      "lat": 39.44511,
      "lng": -79.11081,
      "huc": "020700020207"
    },
    {
      "id": "01595500",
      "name": "NORTH BRANCH POTOMAC RIVER AT KITZMILLER, MD",
      "state": "MD",
      "lat": 39.39389,
      "lng": -79.18169,
      "huc": "02070002"
    },
    {
      "id": "01598500",
      "name": "NORTH BRANCH POTOMAC RIVER AT LUKE, MD",
      "state": "MD",
      "lat": 39.47897,
      "lng": -79.06378,
      "huc": "020700020207"
    },
    {
      "id": "01595000",
      "name": "NORTH BRANCH POTOMAC RIVER AT STEYER, MD",
      "state": "MD",
      "lat": 39.30189,
      "lng": -79.30689,
      "huc": "02070002"
    },
    {
      "id": "01603000",
      "name": "NORTH BRANCH POTOMAC RIVER NEAR CUMBERLAND, MD",
      "state": "MD",
      "lat": 39.62181,
      "lng": -78.77342,
      "huc": "020700020801"
    },
    {
      "id": "01636765",
      "name": "POTOMAC RIVER AT BURKITTSVILLE RD AT BRUNSWICK, MD",
      "state": "MD",
      "lat": 39.30887,
      "lng": -77.63099,
      "huc": "020700080202"
    },
    {
      "id": "0165258890",
      "name": "POTOMAC RIVER AT CAMERON ST DOCK AT ALEXANDRIA, VA",
      "state": "VA",
      "lat": 38.80528,
      "lng": -77.03833,
      "huc": "02070010"
    },
    {
      "id": "01644148",
      "name": "POTOMAC RIVER AT EDWARDS FERRY NEAR POOLESVILLE,MD",
      "state": "MD",
      "lat": 39.09864,
      "lng": -77.47125,
      "huc": "020700080904"
    },
    {
      "id": "01613000",
      "name": "POTOMAC RIVER AT HANCOCK, MD",
      "state": "MD",
      "lat": 39.69756,
      "lng": -78.17789,
      "huc": "020700040504"
    },
    {
      "id": "01620000",
      "name": "POTOMAC RIVER AT HARPERS FERRY, WV",
      "state": "MD",
      "lat": 39.32375,
      "lng": -77.72819,
      "huc": "02070004"
    },
    {
      "id": "01610000",
      "name": "POTOMAC RIVER AT PAW PAW, WV",
      "state": "MD",
      "lat": 39.53886,
      "lng": -78.45561,
      "huc": "02070003"
    },
    {
      "id": "01638500",
      "name": "POTOMAC RIVER AT POINT OF ROCKS, MD",
      "state": "MD",
      "lat": 39.27358,
      "lng": -77.54311,
      "huc": "02070008"
    },
    {
      "id": "01618000",
      "name": "POTOMAC RIVER AT SHEPHERDSTOWN, WV",
      "state": "WV",
      "lat": 39.43472,
      "lng": -77.80139,
      "huc": "020700041106"
    },
    {
      "id": "01646500",
      "name": "POTOMAC RIVER NEAR WASH, DC LITTLE FALLS PUMP STA",
      "state": "MD",
      "lat": 38.94978,
      "lng": -77.12764,
      "huc": "020700081005"
    },
    {
      "id": "01607500",
      "name": "S F SOUTH BRANCH POTOMAC RIVER AT BRANDYWINE, WV",
      "state": "WV",
      "lat": 38.63151,
      "lng": -79.24365,
      "huc": "02070001"
    },
    {
      "id": "01608000",
      "name": "S F SOUTH BRANCH POTOMAC RIVER NR MOOREFIELD, WV",
      "state": "WV",
      "lat": 39.01233,
      "lng": -78.95614,
      "huc": "02070001"
    },
    {
      "id": "01605500",
      "name": "SOUTH BRANCH POTOMAC RIVER AT FRANKLIN, WV",
      "state": "WV",
      "lat": 38.63567,
      "lng": -79.33782,
      "huc": "02070001"
    },
    {
      "id": "01608070",
      "name": "SOUTH BRANCH POTOMAC RIVER NEAR MOOREFIELD, WV",
      "state": "WV",
      "lat": 39.10392,
      "lng": -78.95931,
      "huc": "02070001"
    },
    {
      "id": "01606500",
      "name": "SOUTH BRANCH POTOMAC RIVER NEAR PETERSBURG, WV",
      "state": "WV",
      "lat": 38.99122,
      "lng": -79.17587,
      "huc": "02070001"
    },
    {
      "id": "01608500",
      "name": "SOUTH BRANCH POTOMAC RIVER NEAR SPRINGFIELD, WV",
      "state": "WV",
      "lat": 39.44704,
      "lng": -78.65418,
      "huc": "02070001"
    }
  ]
}

Where the data comes from

Source: USGS streamgage directory and the USGS Water Data service for live readings (public domain).
Freshness: Readings fetched live and edge-cached for 15 minutes.

One install. Every endpoint.

No proprietary SDKs needed. Any HTTP client works. Pick your language and paste.

3languages

5endpoints

RESTarchitecture

1key for all APIs

Fully typed responses — auto-completion in your IDE
Tracks the API in lockstep — new endpoints land same day
One key works across 125+ APIs on the platform

import axios from 'axios';

const { data } = await axios.get(
  'https://api-rivers.dataandapis.com/v1/sources',
  { headers: { 'X-Api-Key': process.env.API_KEY } }
);

River Conditions API · X-Api-Key

Explore the endpoints

Browse request parameters and inspect live example responses.

Available Endpoints

Request Parameters

API URL

Headers

X-Api-Key

Target:

Client:

import axios from 'axios';

const url = 'https://api-rivers.dataandapis.com/v1/sources';
const { data } = await axios.get(url, {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' }
});