https://github.com/yieldhog/usgs_streamflow
Home Assistant integration for real-time USGS stream gauge data (flow, gauge height, water temperature)
https://github.com/yieldhog/usgs_streamflow
hacs hacs-integration home-assistant streamflow usgs
Last synced: 3 months ago
JSON representation
Home Assistant integration for real-time USGS stream gauge data (flow, gauge height, water temperature)
- Host: GitHub
- URL: https://github.com/yieldhog/usgs_streamflow
- Owner: yieldhog
- Created: 2026-03-22T21:13:05.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-03-22T23:09:31.000Z (3 months ago)
- Last Synced: 2026-03-23T14:11:37.925Z (3 months ago)
- Topics: hacs, hacs-integration, home-assistant, streamflow, usgs
- Language: Python
- Homepage:
- Size: 71.3 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# USGS Streamflow for Home Assistant
[](https://github.com/hacs/integration)
[](https://github.com/yieldhog/usgs_streamflow/releases)
A Home Assistant integration that pulls real-time streamflow data from the [USGS National Water Information System (NWIS)](https://waterservices.usgs.gov/) 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 `Active` or `Offline` so seasonal/winter shutdowns are handled cleanly
- **Proper unavailability handling** — sensors mark as `Unavailable` (not `Unknown`) 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)
1. Open HACS in your Home Assistant instance
2. Click the three-dot menu → **Custom repositories**
3. Add `https://github.com/yieldhog/usgs_streamflow` as an **Integration**
4. Find **USGS Streamflow** in HACS and click **Download**
5. Restart Home Assistant
### Manual
1. Download the latest release zip from the [releases page](https://github.com/yieldhog/usgs_streamflow/releases)
2. Extract and copy the `custom_components/usgs_streamflow` folder into your HA `config/custom_components/` directory
3. Restart Home Assistant
## Setup
1. Go to **Settings → Devices & Services → Add Integration**
2. Search for **USGS Streamflow**
3. 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](https://waterdata.usgs.gov/nwis/rt)
4. Pick your gauge from the results list
5. 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](https://waterservices.usgs.gov/rest/IV-Service.html), which is free and requires no API key.
## Contributing
Issues and pull requests welcome at [github.com/yieldhog/usgs_streamflow](https://github.com/yieldhog/usgs_streamflow).