USGS Water Levels & Gauges — New API, Daily Values

Get river water levels, lake/reservoir elevations, and streamflow for any US state or any list of USGS gauges — validated daily values with recent history, freshness status, and a source link on every record — straight from the official USGS Water Data API.

Why this actor

• Built on the NEW USGS API — the one that survives 2027. USGS is decommissioning its legacy waterservices.usgs.gov API in early 2027. Every other USGS water actor on the store reads that dying API (checked their docs — none even mention the shutdown). This actor talks only to the replacement, api.waterdata.usgs.gov, so it keeps working — and your pipeline built on it does too.
• Daily values with history, not just a snapshot. Each record carries the gauge's daily values for your chosen window (up to a year) plus the latest reading — enough to see trend, not just a number.
• Validated, never guessed. Readings outside physical plausibility bounds are dropped and counted, never published. Single-day sensor glitches in level data (a lake "rising" 125 ft for one day — real example) are filtered out. Streamflow is deliberately NOT glitch-filtered — flash floods are real and this actor won't erase them.
• Honest freshness. The USGS "latest" feed includes gauges that died in 2012 (measured). State queries return only gauges reporting within the last 21 days; every record carries freshness (active/delayed/inactive) and age_days, so a stale gauge can never masquerade as current.
• A format change never becomes silent garbage. Every parser opens with a signature check on the API's own payload structure. If USGS changes the format, the affected query fails loudly in SOURCE_STATUS — you will never quietly get wrong columns. States are fetched independently: one state failing leaves the others' data intact.
• Provenance on every record: the official USGS gauge page (official_url) and the exact API query that produced the data (source_url). Verify any row in one click.

Input

Field	Type	Default	Notes
states	array	["Texas"]	2-letter codes or full names. Clear it ([]) for site-id-only runs
siteIds	array	—	USGS site numbers, e.g. 08158000 or USGS-08158000. Returned even if stale (freshness tells the truth)
parameters	array	Gage height + Lake/reservoir elevation	Also: Streamflow. One record per gauge per measurement
periodDays	integer	30	Daily-history window, 1–365
includeSeries	boolean	true	Off = latest readings only — a much faster, much cheaper run
maxSites	integer	100	Distinct gauge sites per run (Texas alone has ~600 active gage-height sites; the default is moderate because of the API's volume rate limit — raise it freely for occasional runs)
maxRecords	integer	5000	One record = one gauge × one measurement

{
  "states": ["CO", "New Mexico"],
  "parameters": ["Streamflow"],
  "periodDays": 90
}

{
  "states": [],
  "siteIds": ["08158000", "USGS-02169000"],
  "parameters": ["Gage height", "Streamflow"],
  "periodDays": 365
}

Output

One dataset item per gauge site per measurement:

{
  "site_id": "USGS-08158000",
  "site_number": "08158000",
  "site_name": "Colorado Rv at Austin, TX",
  "site_type_code": "ST",
  "state": "Texas",
  "county": "Travis County",
  "latitude": 30.2461, "longitude": -97.6801,
  "vertical_datum": null,
  "parameter": "Gage height",
  "parameter_code": "00065",
  "statistic": "daily mean",
  "statistic_id": "00003",
  "unit": "ft",
  "latest_date": "2026-09-04",
  "latest_value": 4.18,
  "freshness": "active",
  "age_days": 1,
  "period_start": "2026-08-06",
  "period_end": "2026-09-05",
  "series": [["2026-08-06", 3.92], ["2026-08-07", 3.95]],
  "n_readings": 30,
  "dropped_readings": 0,
  "official_url": "https://waterdata.usgs.gov/monitoring-location/08158000/",
  "source_url": "https://api.waterdata.usgs.gov/ogcapi/v0/collections/daily/items?...",
  "fetched_at": "2026-09-05T21:14:09Z"
}

• freshness — active (reading within 7 days), delayed (within 45), inactive (older). Computed, never assumed.
• series — [date, value] pairs for the window, validated and (for level parameters) glitch-filtered; null if the history fetch failed for that gauge (reported in SOURCE_STATUS, the latest reading still returns).
• dropped_readings — how many raw points validation removed for this gauge (out-of-bounds or isolated single-day spikes).
• statistic — the daily statistic USGS publishes for this series (mean preferred, then min/max/observation; tidal gauges publish tidal high-high/low-low statistics instead and are carried honestly as such — for those, tidal high-high = the day's peak water level).
• Where a site publishes several elevation datums, one is chosen by fixed ranking (NGVD 29 → NAVD 88 → local datum) — no double records.

The run also writes SOURCE_STATUS to the key-value store: per-state status (ok/failed), record/site counts, failed-series counts, API request count, timing, and a floor warning if a state returned suspiciously few gauges.

Choosing a run shape (cost control)

• Latest levels for a state, cheapest:

  {"states": ["WA"], "includeSeries": false}
  — a handful of API calls, seconds.
• Monitoring dashboard, one basin: put your gauge list in siteIds, periodDays: 30, schedule daily.
• Research pull: periodDays: 365 on a specific site list. (State × 365-day runs are the slowest shape — the actor paces itself to respect the API's rate limits; prefer site lists for long windows.)

Honest limitations

• Daily values, not real-time. This is the daily-values feed (the right one for levels/trend history). The most recent value is usually yesterday's; a reading taken 5 minutes ago won't be here.
• Recent values carry USGS's Provisional status upstream and may be revised by USGS later; this actor reports what USGS publishes at fetch time.
• A state query returns gauges reporting within the last 21 days — long-dead gauges are excluded on purpose (use siteIds to fetch a specific gauge regardless of freshness).
• Coverage is whatever USGS itself operates. Some reservoirs are run by other agencies (TVA, USACE) and have no USGS gauge; this actor cannot invent them.
• The API enforces a volume-weighted rate limit (~1,000 requests/hour). The actor paces itself and honors the API's Retry-After; a very large run (many states × long windows) will be slow rather than wrong.

Typical usages

• Flood/drought monitoring feed: schedule daily, {"states": ["LA", "MS"], "parameters": ["Gage height", "Streamflow"], "periodDays": 14}.
• Lake levels for a property/recreation site: {"states": ["SC"], "parameters": ["Lake or reservoir elevation"]}.
• Hydrology research: site lists with periodDays: 365.
• Migrating off the legacy API before 2027: the output carries the new API's identifiers (site_id, parameter_code, statistic_id) — a working reference for your own migration.

Legality

USGS water data is US-government public-domain data, published specifically for reuse via the official API this actor reads. No logins, no paywalls, no scraping of private sites, no personal data.