USGS Real-Time Water Monitor

Monitor US real-time streamflow, gauge height, and water-quality across USGS gauges. Give it a list of USGS site numbers and parameter codes; it returns one normalized record per reading, with optional threshold-crossed alerts and a changed-since-last-run monitoring mode.

Clean REST/JSON — no browser, no proxy, no login. Data source: USGS (U.S. public domain).

---

What it does

For each run it queries the USGS WaterServices Instantaneous Values (IV) service for your sites + parameters, normalizes the response, applies your filters, and pushes one dataset item per reading.

• Latest snapshot (default): the most recent reading per site+parameter.
• Look-back window: set period (e.g. P1D, PT6H) to return every reading in that window.
• Since a date: sinceDate returns only readings on/after an instant.
• Change monitor: monitorChangesOnly persists the last-seen timestamp per series (in the Actor's key-value store) and, on the next scheduled run, returns only new readings.
• Threshold alerts: thresholds attaches an alert object to readings that cross an above/below bound; onlyAlerts returns just the crossings.

Inputs

Input	Type	Notes
sites (required)	string[]	USGS site numbers, e.g. 01646500 (Potomac @ Washington DC)
parameterCodes	string[]	e.g. 00060 discharge, 00065 gauge height, 00010 water temp
period	string	ISO-8601 duration, e.g. P1D. Empty = latest reading only
sinceDate	string	Return readings on/after this ISO datetime
monitorChangesOnly	boolean	Return only readings newer than the previous run
thresholds	object[]	[{ "site":"01646500","parameterCode":"00065","above":10,"below":1 }]
onlyAlerts	boolean	Return only threshold-crossing readings
maxResultsPerSite	integer	Cap readings per site (0 = no cap)
apiKey	string (secret)	Not needed today; reserved for the 2027 API cutover
proxyConfiguration	object	Optional; the API is open and needs no proxy. Default: none

Output — one record per reading

{
  "site": "01646500",
  "siteName": "POTOMAC RIVER NEAR WASH, DC LITTLE FALLS PUMP STA",
  "agencyCode": "USGS",
  "latitude": 38.94977778,
  "longitude": -77.12763889,
  "parameterCode": "00060",
  "parameterName": "Streamflow, ft³/s",
  "unit": "ft3/s",
  "methodId": 69928,
  "value": 5500,
  "valueRaw": "5500",
  "qualifiers": ["P"],
  "dateTime": "2026-07-09T17:50:00.000-04:00",
  "isNew": true,
  "alert": { "type": "threshold-crossed", "direction": "above", "threshold": 5000, "value": 5500 },
  "source": "waterservices-iv",
  "fetchedAt": "2026-07-09T22:15:00.000Z"
}

value is numeric (USGS no-data sentinel -999999 is mapped to null). qualifiers ["P"] = provisional data (subject to revision). isNew is true when a reading is newer than the previous run's watermark (only meaningful with monitorChangesOnly). alert is present only on threshold-crossing readings.

Control records (not charged)

Two non-reading records may be pushed to signal run state. Neither triggers a reading-returned charge:

Record	When	Shape
_noData	USGS returned no readings for the requested sites/parameters (bad site number, inactive gauge, or empty window)	{ "_noData": true, "sites": [...], "parameterCodes": [...], "message": "...", "fetchedAt": "..." }
_error	The fetch failed after retries, or normalization threw	{ "_error": true, "sites": [...], "parameterCodes": [...], "message": "...", "fetchedAt": "..." }

_noData keeps a zero-result run green and auditable rather than pushing a silent empty dataset.

Pricing (pay-per-event)

One reading-returned event is charged per record pushed to the dataset — including alert records. Cost scales with results, not runtime. Use onlyAlerts / maxResultsPerSite / monitorChangesOnly to keep spend proportional to signal.

Data source & attribution

Data © nobody — U.S. public domain, courtesy of the U.S. Geological Survey (USGS Water Data for the Nation). No key and no attribution are required; we credit USGS as a courtesy. Provisional data are subject to revision (see the P qualifier). Full compliance record: ./COMPLIANCE.md.

⚠️ Maintenance obligation — 2027 API migration

The USGS WaterServices APIs this Actor uses are being decommissioned in Q1 2027 (intentional degradation not before Aug 2026). The replacement is https://api.waterdata.usgs.gov. The GeoJSON parser for the new API is already in src/usgs.js (normalizeNewApiItems), but its data lives behind a path that robots.txt currently disallows for bots — cutover must use the documented, API-key'd path and re-verify robots.txt at that time. Complete the cutover before Q1 2027. See ./COMPLIANCE.md §3–§4.