{"openapi":"3.1.0","info":{"title":"USGS Streamflow API","version":"1.0.0","description":"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.","contact":{"name":"PremiumApi","url":"https://www.oanor.com/by/premiumapi"}},"servers":[{"url":"https://api.oanor.com/streamflow-api","description":"oanor gateway"}],"tags":[{"name":"Streamflow"},{"name":"Meta"}],"components":{"securitySchemes":{"oanorKey":{"type":"apiKey","in":"header","name":"x-oanor-key","description":"Get your key at https://www.oanor.com/developer/keys"}}},"security":[{"oanorKey":[]}],"paths":{"/v1/gauge":{"get":{"operationId":"get_v1_gauge","tags":["Streamflow"],"summary":"Latest live observation for a USGS gauge","description":"","parameters":[{"name":"site","in":"query","required":true,"description":"USGS site number, e.g. 01646500 (Potomac River)","schema":{"type":"string"},"example":"01646500"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/nearby":{"get":{"operationId":"get_v1_nearby","tags":["Streamflow"],"summary":"Gauges within a radius of a coordinate","description":"","parameters":[{"name":"lat","in":"query","required":false,"description":"Latitude (-90..90)","schema":{"type":"string"},"example":"38.9"},{"name":"lon","in":"query","required":false,"description":"Longitude (-180..180)","schema":{"type":"string"},"example":"-77.0"},{"name":"radius_km","in":"query","required":false,"description":"Search radius in km (1-5000, default 100)","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Max results (1-100, default 10)","schema":{"type":"string"}}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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":-76.94328,"distance_km":4.9},{"name":"BEAVERDAM CREEK NEAR CHEVERLY, MD","site":"01651730","state":"MD","latitude":38.91631,"longitude":-76.93431,"distance_km":6},{"name":"NORTHWEST BR ANACOSTIA RIVER NR HYATTSVILLE, MD","site":"01651000","state":"MD","latitude":38.95256,"longitude":-76.96514,"distance_km":6.6},{"name":"NORTHWEST BRANCH ANACOSTIA RIVER AT BRENTWOOD, MD","site":"01651003","state":"MD","latitude":38.94897,"longitude":-76.95622,"distance_km":6.6},{"name":"ROCK CREEK AT JOYCE RD WASHINGTON, DC","site":"01648010","state":"DC","latitude":38.96017,"longitude":-77.04206,"distance_km":7.6},{"name":"Luzon Branch above Rock Creek at Washington DC","site":"01648011","state":"DC","latitude":38.96169,"longitude":-77.04139,"distance_km":7.7}],"radius_km":100},"meta":{"timestamp":"2026-05-31T06:28:06.717Z","request_id":"bda37d85-59a7-4e5a-8da7-60902c9b3943"},"status":"ok","message":"Nearby sites listed","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/search":{"get":{"operationId":"get_v1_search","tags":["Streamflow"],"summary":"Search the gauge catalogue","description":"","parameters":[{"name":"q","in":"query","required":false,"description":"Name search, e.g. potomac","schema":{"type":"string"},"example":"potomac"},{"name":"state","in":"query","required":false,"description":"2-letter US state, e.g. CO","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Results per page (1-100, default 20)","schema":{"type":"string"},"example":"20"},{"name":"offset","in":"query","required":false,"description":"Pagination offset","schema":{"type":"string"},"example":"0"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"count":20,"limit":20,"query":"potomac","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","state":"MD","latitude":39.69756,"longitude":-78.17789},{"name":"POTOMAC RIVER AT HARPERS FERRY, WV","site":"01620000","state":"MD","latitude":39.32375,"longitude":-77.72819},{"name":"POTOMAC RIVER AT BURKITTSVILLE RD AT BRUNSWICK, MD","site":"01636765","state":"MD","latitude":39.30887,"longitude":-77.63099},{"name":"POTOMAC RIVER AT POINT OF ROCKS, MD","site":"01638500","state":"MD","latitude":39.27358,"longitude":-77.54311},{"name":"POTOMAC RIVER AT EDWARDS FERRY NEAR POOLESVILLE,MD","site":"01644148","state":"MD","latitude":39.09864,"longitude":-77.47125},{"name":"POTOMAC RIVER NEAR WASH, DC LITTLE FALLS PUMP STA","site":"01646500","state":"MD","latitude":38.94978,"longitude":-77.12764},{"name":"POTOMAC RIVER AT CAMERON ST DOCK AT ALEXANDRIA, VA","site":"0165258890","state":"VA","latitude":38.80528,"longitude":-77.03833},{"name":"NORTH BRANCH POTOMAC RIVER AT BARNUM, WV","site":"01595800","state":"WV","latitude":39.44511,"longitude":-79.11081},{"name":"NORTH BRANCH POTOMAC RIVER AT PINTO, MD","site":"01600000","state":"WV","latitude":39.56681,"longitude":-78.83956},{"name":"SOUTH BRANCH POTOMAC RIVER AT FRANKLIN, WV","site":"01605500","state":"WV","latitude":38.63567,"longitude":-79.33782},{"name":"N F SOUTH BRANCH POTOMAC RIVER AT CABINS, WV","site":"01606000","state":"WV","latitude":38.98455,"longitude":-79.23365},{"name":"SOUTH BRANCH POTOMAC RIVER NEAR PETERSBURG, WV","site":"01606500","state":"WV","latitude":38.99122,"longitude":-79.17587},{"name":"S F SOUTH BRANCH POTOMAC RIVER AT BRANDYWINE, WV","site":"01607500","state":"WV","latitude":38.63151,"longitude":-79.24365},{"name":"S F SOUTH BRANCH POTOMAC RIVER NR MOOREFIELD, WV","site":"01608000","state":"WV","latitude":39.01233,"longitude":-78.95614},{"name":"SOUTH BRANCH POTOMAC RIVER NEAR MOOREFIELD, WV","site":"01608070","state":"WV","latitude":39.10392,"longitude":-78.95931}]},"meta":{"timestamp":"2026-05-31T06:28:06.797Z","request_id":"0f21d832-e80d-4c76-846b-dee3bad2897f"},"status":"ok","message":"Sites listed","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/meta":{"get":{"operationId":"get_v1_meta","tags":["Meta"],"summary":"Totals & source","description":"","parameters":[],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}}},"x-oanor-pricing":[{"slug":"free","name":"Free","price_cents_month":0,"monthly_call_quota":3000,"rps_limit":2,"hard_limit":true},{"slug":"starter","name":"Starter","price_cents_month":600,"monthly_call_quota":40000,"rps_limit":8,"hard_limit":true},{"slug":"pro","name":"Pro","price_cents_month":1800,"monthly_call_quota":220000,"rps_limit":20,"hard_limit":true},{"slug":"mega","name":"Mega","price_cents_month":4700,"monthly_call_quota":1100000,"rps_limit":50,"hard_limit":true}],"x-oanor-marketplace-url":"https://www.oanor.com/api/streamflow-api"}