USGS NWIS River Streamflow & Fishing Conditions Scraper

Pulls real-time discharge, gage height, and water temperature from every active USGS stream gage in any US state. Returns one record per gage/parameter with site metadata, the latest instantaneous measurement, and a derived flow condition (low / normal / high).

Built for anglers, fishing guides, outfitters, and app developers who need a programmatic answer to "is this river fishable today?"

What It Does

Calls the USGS Water Services instantaneous-values (IV) API — a completely open federal dataset, no API key required — and returns structured records for every active stream gage in the requested states.

Parameters collected:

• 00060 — Discharge / streamflow (cubic feet per second)
• 00065 — Gage height (feet)
• 00010 — Water temperature (°C)

Flow condition derivation (for discharge only): based on USGS qualifier codes present in each measurement. > = exceeds upper reliable measurement range → high; < = below lower range → low; normal provisional/approved reads return blank (no extreme condition detected).

Input

Field	Type	Default	Description
stateCodes	array	["CO"]	Two-letter US state abbreviations (e.g. ["CO", "MT", "WY"]). Leave empty to scrape all 50 states.
parameterCodes	array	["00060", "00065", "00010"]	USGS parameter codes to collect.
maxItems	integer	10	Maximum number of records to return. Leave empty for all records.

Example — Colorado discharge only:

{
  "stateCodes": ["CO"],
  "parameterCodes": ["00060"],
  "maxItems": 100
}

Example — Full trout-fishing pack (all 50 states, all three parameters):

{
  "stateCodes": [],
  "parameterCodes": ["00060", "00065", "00010"]
}

Output

One record per gage/parameter combination.

Field	Type	Description
site_no	string	USGS site identification number
site_name	string	River or stream station name
state_code	string	Two-character FIPS state code (e.g. 08 for Colorado)
county_code	string	Five-character FIPS county code
latitude	string	Decimal latitude (WGS84)
longitude	string	Decimal longitude (WGS84)
parameter_code	string	USGS parameter code (00060 / 00065 / 00010)
parameter_name	string	Human-readable parameter name (e.g. Streamflow, ft3/s)
measurement_datetime	string	ISO 8601 datetime of the latest measurement
value	string	Measured value (numeric string, or NoData)
unit	string	Unit of measurement (ft3/s / ft / deg C)
qualifiers	string	Comma-separated USGS qualifier codes (P=provisional, A=approved, e=estimated)
flow_condition	string	Derived condition for discharge: low / high / blank
source_url	string	USGS NWIS link for this site and parameter
scraped_at	string	ISO 8601 UTC timestamp when this record was collected

Example record:

{
  "site_no": "06752000",
  "site_name": "CACHE LA POUDRE RIV AT CANYON MOUTH NR FT COLLINS, CO",
  "state_code": "08",
  "county_code": "08069",
  "latitude": "40.67676",
  "longitude": "-105.14241",
  "parameter_code": "00060",
  "parameter_name": "Streamflow, ft3/s",
  "measurement_datetime": "2026-05-21T10:00:00.000-06:00",
  "value": "312",
  "unit": "ft3/s",
  "qualifiers": "P",
  "flow_condition": "",
  "source_url": "https://waterdata.usgs.gov/nwis/uv?site_no=06752000&agency_cd=USGS&parameterCd=00060&period=P7D",
  "scraped_at": "2026-05-21T16:15:03.000Z"
}

Use Cases

• Fishing trip planning — query discharge and temperature for a specific state before heading out
• River fishing apps — feed real-time gage data into a "fishability" score
• Outfitter dashboards — monitor multiple rivers across a region simultaneously
• Research / conservation — time-series analysis of flow conditions across gage networks
• Alert systems — detect high-flow or low-flow conditions for float trip scheduling

Notes

• Coverage: ~8,000-10,000+ active stream gages nationwide. Colorado alone has ~356 discharge gages.
• Freshness: USGS IV data is typically updated every 15 minutes.
• No API key required: USGS Water Services is a free federal open-data service.
• Rate limits: USGS requests polite use. The actor uses a 200ms delay between state requests.
• Full-country run: Scraping all 50 states with all three parameters returns ~50,000-80,000 records. Use maxItems to cap output for quick queries.