USGS NWIS Streamflow & Gage Height Monitor

Real-time streamflow (discharge, cfs) and gage height (ft) from the U.S. Geological Survey National Water Information System (NWIS), delivered as clean, flat, one-row-per-site records. The actor does the hard part for you: it pulls the deeply nested WaterML-in-JSON response, flattens it, computes the change vs the prior reading, and flags any site over a flood-stage / alert threshold you set. Keyless, public-domain USGS data.

Who it's for

• Agriculture & irrigation districts — watch intake streams and canals for low/high flow.
• Water utilities & dam operators — track river stage and discharge at supply and downstream points.
• Flood / P&C insurers & risk teams — threshold alerts on rising gages near insured exposure.
• Environmental consultants & hydrologists — normalized time-stamped readings ready for analysis.
• Researchers & data engineers — skip the WaterML parsing; get tidy rows and deltas.

What it does

1. Accepts a list of USGS site numbers OR a state code (every gaging site in the state).
2. Pulls the latest instantaneous (iv) or daily (dv) value for one or more parameters (00060 discharge, 00065 gage height).
3. Optionally widens the window (period, e.g. PT2H) so it can compute a change delta + direction (rising/falling/steady) vs the prior reading.
4. Applies an optional global threshold or per-site thresholds and sets above_threshold + amount_over_threshold.
5. onlyAlerts mode returns only sites at or above their threshold.

Example input

{
  "sites": ["01646500", "01638500"],
  "parameterCd": "00060",
  "service": "iv",
  "period": "PT2H",
  "thresholdValue": "25000",
  "onlyAlerts": false
}

State-wide flood watch:

{ "stateCd": "VA", "parameterCd": "00065", "thresholdValue": "10", "onlyAlerts": true }

Output fields

Field	Description
site_no / site_name	USGS station number and name
agency	Reporting agency (USGS)
state / state_fips / county_fips	USPS state, FIPS state, FIPS county
huc	Hydrologic Unit Code
lat / lon	Site coordinates (EPSG:4326)
parameter_code / parameter_name / unit	e.g. 00060 / Discharge / ft3/s
value / datetime	Latest reading and its timestamp
qualifier / provisional	Qualifier code(s); provisional flag (P)
prior_value / prior_datetime	Previous reading (when a period is set)
change / change_direction	Delta vs prior; rising / falling / steady
threshold_value / above_threshold / amount_over_threshold	Threshold applied, over/under flag, and margin

Use as an MCP tool

This actor is callable by AI agents (Claude, Cursor, etc.) via mcp.apify.com. Its input and output schemas carry field-level descriptions, so an agent can chain it: e.g. "get the latest Potomac River streamflow and tell me if it is above 25,000 cfs" maps directly to sites + thresholdValue.

FAQ

Where does the data come from? USGS Water Services (waterservices.usgs.gov/nwis/iv and /dv), public-domain, no API key.

How do I find a site number? Use the USGS site map or NWIS. Common example: 01646500 = Potomac River near Washington, DC (Little Falls).

How do I get streamflow vs gage height? parameterCd = 00060 for discharge (cfs), 00065 for gage height (ft). Comma-separate for both.

Why is my value marked provisional? Recent USGS readings carry a P qualifier until reviewed; provisional is true for those.

Can I get a change/delta? Yes — set a period (e.g. PT2H or P1D) so more than one reading is returned; the actor uses the last two to compute change and change_direction.

Can I monitor a whole state for flooding? Yes — set stateCd, a thresholdValue, and onlyAlerts: true.

Notes & caveats

• A statewide (stateCd) query can return hundreds of sites; sites with no current reading are omitted.
• Real-time values are provisional and subject to USGS revision — verify before operational use.
• change is only populated when the response contains at least two readings (set a period).