{ "openapi": "3.1.0", "info": { "title": "River Conditions API", "version": "1.0.0", "description": "Live streamflow, gage height and water temperature from 11,605 USGS river gauges, with nearest-gauge lookup.\n\nLive 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).", "contact": { "name": "Data and APIs", "url": "https://dataandapis.com/contact" }, "termsOfService": "https://dataandapis.com/terms-of-service", "license": { "name": "Data and APIs Terms of Service", "url": "https://dataandapis.com/terms-of-service" }, "x-logo": { "url": "https://dataandapis.com/images/rivers.webp" } }, "externalDocs": { "description": "Documentation, live tester and pricing", "url": "https://dataandapis.com/apis/rivers" }, "servers": [ { "url": "https://api-rivers.dataandapis.com" } ], "tags": [ { "name": "Data", "description": "River Conditions API belongs to the Data category of the Data and APIs catalog." } ], "paths": { "/v1/sources": { "get": { "operationId": "dataSources", "summary": "Data Sources", "description": "Data Sources endpoint of the River Conditions API. Costs 2 tokens per call.", "externalDocs": { "url": "https://dataandapis.com/apis/rivers/data-sources" }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "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" } ] } } } }, "401": { "description": "Missing or invalid API key" }, "402": { "description": "Subscription past due; the response carries a payment_url" }, "429": { "description": "Monthly token allowance exhausted" } }, "security": [ { "ApiKey": [] } ] } }, "/v1/rivers/sites/{id}": { "get": { "operationId": "gaugeDetail", "summary": "Gauge Detail", "description": "Gauge Detail endpoint of the River Conditions API. Costs 2 tokens per call.", "externalDocs": { "url": "https://dataandapis.com/apis/rivers/gauge-detail" }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "09380000" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "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 } } } } } }, "401": { "description": "Missing or invalid API key" }, "402": { "description": "Subscription past due; the response carries a payment_url" }, "429": { "description": "Monthly token allowance exhausted" } }, "security": [ { "ApiKey": [] } ] } }, "/v1/rivers/conditions": { "get": { "operationId": "liveConditions", "summary": "Live Conditions", "description": "Live Conditions endpoint of the River Conditions API. Costs 2 tokens per call.", "externalDocs": { "url": "https://dataandapis.com/apis/rivers/live-conditions" }, "parameters": [ { "name": "sites", "in": "query", "required": true, "schema": { "type": "string" }, "example": "01646500,09380000" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "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 } } } ] } } } }, "401": { "description": "Missing or invalid API key" }, "402": { "description": "Subscription past due; the response carries a payment_url" }, "429": { "description": "Monthly token allowance exhausted" } }, "security": [ { "ApiKey": [] } ] } }, "/v1/rivers/nearest": { "get": { "operationId": "nearestGauges", "summary": "Nearest Gauges", "description": "Nearest Gauges endpoint of the River Conditions API. Costs 2 tokens per call.", "externalDocs": { "url": "https://dataandapis.com/apis/rivers/nearest-gauges" }, "parameters": [ { "name": "lat", "in": "query", "required": true, "schema": { "type": "string" }, "example": "40.01" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "example": "5" }, { "name": "lng", "in": "query", "required": true, "schema": { "type": "string" }, "example": "-105.27" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "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 } } } ] } } } }, "401": { "description": "Missing or invalid API key" }, "402": { "description": "Subscription past due; the response carries a payment_url" }, "429": { "description": "Monthly token allowance exhausted" } }, "security": [ { "ApiKey": [] } ] } }, "/v1/rivers/sites": { "get": { "operationId": "searchGauges", "summary": "Search Gauges", "description": "Search Gauges endpoint of the River Conditions API. Costs 2 tokens per call.", "externalDocs": { "url": "https://dataandapis.com/apis/rivers/search-gauges" }, "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "example": "potomac" }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "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" } ] } } } }, "401": { "description": "Missing or invalid API key" }, "402": { "description": "Subscription past due; the response carries a payment_url" }, "429": { "description": "Monthly token allowance exhausted" } }, "security": [ { "ApiKey": [] } ] } } }, "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "Create a free key at https://dataandapis.com/sign-up. 500 tokens a month on the Free plan; this API costs 2 tokens per call." } } }, "security": [ { "ApiKey": [] } ] }