USGS Streamflow & Water Levels Scraper API

Query the official USGS National Water Information System (NWIS) Instantaneous Values JSON service and receive one dataset item per site/parameter time series. Use it for bounded streamflow, discharge, gage-height, watershed monitoring, research, dashboards, and source-backed data pipelines.

Deterministic first run

{
  "sites": ["01646500"],
  "parameterCd": ["00060", "00065"],
  "siteStatus": "all",
  "includeHistory": false,
  "observationsPerSeries": 24,
  "maxResults": 2
}

This requests the Potomac River near Washington (01646500) and normally returns two rows: discharge (00060) and gage height (00065). It returns at most 2 paid items, so the maximum first-run charge is $0.0041: $0.0001 start + 2 × $0.002/item. Missing/sentinel readings are never converted to zero.

Inputs

Choose exactly one geography selector:

• sites: up to 100 USGS site numbers
• stateCd: state/territory abbreviation
• countyCd: five-digit county FIPS
• huc: hydrologic unit code
• bbox: west,south,east,north

Additional controls:

• parameterCd: up to 20 USGS parameter codes
• period, or paired startDT + endDT (mutually exclusive)
• siteStatus: all, active, or inactive
• qualifiers: optional exact codes such as P or A
• includeHistory and observationsPerSeries (maximum 1,000 nested observations)
• maxResults: total series rows across the entire request (maximum 500)

The actor rejects missing or conflicting geography selectors before contacting USGS. It never issues an unbounded national request.

Parameter guidance

• 00060: discharge / streamflow, commonly cubic feet per second
• 00065: gage height, commonly feet

USGS determines the available parameters, statistic, units, methods, and observations for each site. Do not assume every site offers both codes or the same unit. Other NWIS parameter codes may be supplied explicitly.

Output

Each FOUND row includes site ID/name, coordinates, state/county/HUC, site type, time zones, parameter code/name/description, unit, statistic, latest value/time, source qualifier codes and descriptions, method, bounded observations, exact source request URL, retrieval time, and coverage disclosure. Explicit NO_MATCH, INVALID_INPUT, and SOURCE_UNAVAILABLE records prevent silent empty runs.

Important evidence boundaries

USGS instantaneous values can be provisional, revised, delayed, equipment-affected, missing, or unavailable. Qualifiers such as provisional (P) and approved (A) are preserved exactly; they are not rewritten into a quality judgment. A missing value or USGS noDataValue is omitted, never represented as zero.

These observations are not flood forecasts, regulatory determinations, navigational guidance, or emergency instructions. Do not use this actor as a warning system or safety-of-life source. Follow National Weather Service warnings and official local emergency authorities. A bounded no-match does not prove a site, parameter, or observation does not exist.

Source and reliability

Source: https://waterservices.usgs.gov/nwis/iv/ (USGS NWIS Instantaneous Values, WaterML JSON). No API credential is required. Requests use a descriptive User-Agent, bounded timeout and response size, and retries for transport/body-read failures, malformed transient responses, HTTP 408/429/5xx, and Retry-After.