I used to use a REST sensor for this, created an integration (with the help of Claude but thoroughly tested) if anyone else finds it useful
USGS Streamflow for Home Assistant
A Home Assistant integration that pulls real-time streamflow data from the USGS National Water Information System (NWIS) for any active stream gauge in the United States.
Features
- Search by name or site number — find any active USGS stream gauge via the setup wizard
- Up to 3 sensors per gauge — Gauge Height (ft), Discharge (ft³/s), and Water Temperature (°C) where available
- Station Status sensor — shows
ActiveorOfflineso seasonal/winter shutdowns are handled cleanly - Proper unavailability handling — sensors mark as
Unavailable(notUnknown) when a gauge is seasonally decommissioned - Polled every 15 minutes — matches USGS data update frequency
- Multiple gauges — add as many stations as you want, each becomes its own device
Requirements
- Home Assistant 2026.3 or newer
- HACS installed
Installation
Via HACS (recommended)
- Open HACS in your Home Assistant instance
- Click the three-dot menu → Custom repositories
- Add
https://github.com/yieldhog/usgs_streamflowas an Integration - Find USGS Streamflow in HACS and click Download
- Restart Home Assistant
Manual
- Download the latest release zip from the releases page
- Extract and copy the
custom_components/usgs_streamflowfolder into your HAconfig/custom_components/directory - Restart Home Assistant
Setup
- Go to Settings → Devices & Services → Add Integration
- Search for USGS Streamflow
- Enter a stream or station name (e.g.
Bear Creek) and a two-letter state code (e.g.CO)- You can also paste a USGS site number directly (e.g.
06711565) — no state code needed - Not sure of your site number? Search on the USGS Water Resources site
- You can also paste a USGS site number directly (e.g.
- Pick your gauge from the results list
- Repeat to add additional gauges
Sensors
Each configured gauge creates a device with up to 4 entities:
| Entity | Unit | Notes |
|---|---|---|
| Gauge Height | ft | Water level above the gauge datum |
| Discharge | ft³/s | Volumetric flow rate (CFS) |
| Water Temperature | °C | Not available at all gauges |
| Station Status | — | Active or Offline |
The Station Status entity stays active even when the gauge is offline for the season, and includes an offline_reason attribute explaining why.
Measurement sensors for parameters a gauge never reports (e.g., Water Temperature at a gauge with no thermistor) will show as Unavailable after the first successful data fetch.
Data Source
All data comes from the USGS NWIS Instantaneous Values API, which is free and requires no API key.
Contributing
Issues and pull requests welcome at github.com/yieldhog/usgs_streamflow.