NWPS River Floods smart home integration, free and open source

US river levels, flood categories and official crest forecasts from the NOAA Weather Service.
Brings the river levels of the United States, their flood category and the official crest forecast of the NOAA National Weather Service into Gladys, from the public API of the National Water Prediction Service (NWPS, the successor of AHPS). No account, no key.
This is a complement, not a safety alert system. Data can be late, missing or wrong, and the integration depends on your Gladys, your Internet access and a public service. In a flood, follow the official warnings (weather.gov, your local emergency management, 911). This integration is not affiliated with NOAA or the National Weather Service. Tested against the live NWPS API, not yet on a real Gladys installation: feedback welcome.
What you get
- One device per gauge you follow: the water level (stage) in feet or metres, the flow when the gauge reports one, the flood category of the NWS (no flooding, action stage, minor, moderate, major flooding) as a risk level and in words, and the time of the last reading.
- At the gauges the NWS forecasts (forecast points), the forecast crest: the highest level of the current official forecast, its time and its flood category.
- What the USGS gauges already in the store do not give: the flood stages of the NWS and its forecasts. Readings themselves often come from the USGS: the NWPS relays them.
- A scene trigger "River flood category rises", for an observed or a forecast rise.
- A dashboard widget: your gauges with their level and category, or one gauge with its forecast crest.
- A "Find gauges" button that lists the gauges around your house.
Requirements
- Gladys Assistant 5.3.2 or later (the m³/s unit of the flow in metric units).
- Internet access from Gladys: the integration reads
api.water.noaa.gov. - For "around my house" and "Find gauges": the location of your house in Gladys (Settings, Houses). With several houses, choose yours in the House setting. The integration asks for it at installation (the "location" permission); it is only used to find the nearest gauges, rounded to about 5 km before it leaves Gladys, never stored nor logged.
- The United States (and the few gauges of the NWS in Puerto Rico and on the borders).
Configuration
Settings
| Setting | What it does |
|---|---|
| Gauge codes | NWS codes (four letters and a digit) separated by commas, BRKM2, ARCF1, or the addresses of their pages, https://water.noaa.gov/gauges/brkm2. |
| House | The house whose location is used by "Around my house" and "Find gauges". Empty: the first house of Gladys that has a location. |
| Around my house | Also follows the 3 nearest gauges in service and reporting, within 5, 10 or 25 miles of your house. Off by default. |
| Units | Feet, cfs (default, the units of the NWS) or metres, m³/s, for the new devices. |
| Refresh interval | 15 (default), 20 or 30 minutes. |
| Language of the feature names | Names of the features of new devices, and language of their texts and of the scene variables. French by default. |
At most 20 gauges are followed. Save, then open the Discover tab and create the devices you want. A gauge whose device you created stays followed even if you remove its code from the settings: delete the device to stop.
Changing the units does not change the devices already created: their features keep the unit they were created with, and the values follow it. Click Update on a device in the Discover tab to switch it (its history then mixes both units).
Finding your gauges
The Find gauges button lists the gauges in service around the house chosen in the settings (25 miles, or the chosen distance), nearest first, with their code, distance, current category and "forecast" when the NWS forecasts them. Copy the codes you want into Gauge codes, then save. The code of a gauge is also shown on its page of water.noaa.gov.
Devices
One device per gauge, named like the NWS names it ("Potomac River near Washington DC (Little
Falls)"), with the code as NWS_LID and the state as STATE in its parameters. Its features
are read-only:
| Feature | Type (Gladys) | Value |
|---|---|---|
| Water level | Liquid depth | Stage at the gauge, in feet or metres, above the gauge datum (an elevation at some lakes and dams). |
| Flow (cfs) / Flow | Water flow | When the gauge reports one: in cubic feet per second (a unit Gladys does not have: the name says it) or m³/s. |
| Flood level | Risk | When the gauge has flood stages: 0 no flooding (action stage included), 1 minor, 2 moderate, 3 major flooding. |
| Flood category | Text | The category in words: No flooding, Action stage, Minor flooding… or why there is none (No recent reading…). |
| Last reading | Text | Time of the last reading, in the time zone of Gladys. |
| Forecast crest | Liquid depth or flow | Forecast points only: the highest level of the current forecast (a flow at the few gauges forecast by flow). |
| Time of the forecast crest | Text | Its time, or "No current forecast". |
| Forecast flood level | Risk | The flood level of the crest, 0 when there is no current forecast. |
| Forecast flood category | Text | The category of the crest in words. |
A reading older than 24 hours is not sent again: the level then shows "no recent value" in Gladys, and the category "No recent reading".
When a forecast is withdrawn, the forecast crest keeps its last value: its time and category then read "No current forecast", and its flood level 0.
Flood categories
The NWS defines, for each forecast point and many other gauges, an action stage (time to prepare, no flooding yet) and the stages of minor, moderate and major flooding, from the impacts seen in past floods. The integration publishes the category the NWS computes: it does not compare the levels itself. A gauge without flood stages ("No flood stages") has no flood level feature. Many forecast points are only forecast during high water: between two events, their forecast reads "No current forecast".
Dashboard widget
Add the River gauges widget to a dashboard:
- without a gauge chosen: one line per gauge with its level and category, green (no flooding), yellow (action stage, minor) or red (moderate, major), and a heading when a gauge is in flood or forecast in flood;
- with a gauge chosen: its level and flow tiles, its category, the forecast crest with its time and category, its flood stage and its last reading.
The levels of the lines follow the units of your Gladys profile; the tiles show the unit of the features. The water.noaa.gov button opens the page of the gauge; a setting hides it.
Scene triggers
River flood category rises fires when the category of a created gauge goes up to action
stage, minor, moderate or major flooding, observed or forecast. Filters: the gauge, observed or
forecast, the new category. Variables for your messages: gauge_name, category_name,
source_name (observed or forecast), value (the level with its unit) and time (of the
reading or of the crest), in the language of the configuration.
It fires once per rise: again only after the category went down, or after the forecast was withdrawn. The last categories are kept
in /data, so a rise during a restart fires once, and the first reading of a new gauge fires
nothing.
For a threshold of your own, use the native trigger of Gladys on a device value: "Flood level greater than or equal to 1" (minor flooding), or "Forecast crest above 9 ft".
Scene examples
- Flood forecast: trigger "River flood category rises", forecast, minor, moderate or major → send the message "{{gauge_name}}: {{category_name}} forecast, crest {{value}} at {{time}}".
- Minor flooding observed: trigger on the device value "Flood level ≥ 1" → notify and switch on a warning light.
- Back to normal: trigger on the device value "Flood level = 0" → send "The river is back below flood stage".
Data source, quotas and licence
- Source: the National Water Prediction Service of the NOAA National Weather Service,
https://api.water.noaa.gov/nwps/v1/(/gauges/{lid}for each gauge,/gauges?bbox…for the gauges around the house). Data of the U.S. government, public domain; credit: NOAA / NWS. - No account, no key, no published quota. The integration asks for each followed gauge once per refresh (every 15 minutes by default, 20 gauges at most), one after the other, with a User-Agent naming the integration, and looks for the gauges around the house once a day.
- Readings of many gauges come from the USGS and other partners, relayed by the NWPS.
Troubleshooting
- "Unknown gauge codes": a code of the settings is not an NWS gauge. Check it on water.noaa.gov, or use Find gauges. A USGS site number (8 digits) is not an NWS code.
- "The NWPS API does not answer": Gladys cannot reach
api.water.noaa.gov, or the service is down. The integration tries again at every refresh, and the status comes back by itself. - "No house of Gladys has a location": set the location of your house in Settings, Houses, or turn "Around my house" off.
- No forecast crest: the gauge is not a forecast point, or the NWS has no current forecast for it (common outside high water).
- Old values: the last reading is shown in "Last reading". A gauge that stopped reporting reads "No recent reading".
- Logs: Integrations → NWPS River Floods → logs;
LOG_LEVEL=debugshows every refresh.
Limits
- A complement, not a safety alert system: the NWS warnings and your local authorities prevail.
- The NWPS gives the crest of the forecast, not the whole forecast curve nor its uncertainty.
- Flood categories exist only where the NWS defined flood stages.
- The flow in cfs has no unit in Gladys (the name says "cfs"); in metric units it is in m³/s.
- Developed and tested against the live NWPS API, without a real Gladys installation: feedback welcome.
Configuration settings
These are the settings NWPS River Floods asks for in its configuration screen in Gladys.
| Setting | Type | Required | Description |
|---|---|---|---|
| Your gauges | section | No | Follow the river gauges of the National Weather Service: by code, or the nearest ones to your house. "Find gauges" below lists them. Save, then create the devices in the Discover tab. |
| Sources and limits | section | No | Data of the NOAA National Weather Service (public domain), read without an account. A complement, not a safety alert system: the official warnings prevail. Not affiliated with NOAA or the NWS. |
| Gauge codes | string | No | NWS codes separated by commas, or the addresses of their water.noaa.gov pages. |
| House | select | No | The house whose location is used by "Around my house" and by "Find gauges". Empty: the first house of Gladys that has a location. |
| Around my house | select | No | Also follow the 3 nearest gauges in service within this distance of your house. |
| Units | select | No | Units of the new devices. Changing it: "Update" the devices in the Discover tab. |
| Refresh interval | select | No | Gauges report every 5 to 60 minutes, forecasts are issued a few times a day. |
| Language of the feature names | select | No | Names given to the features of new devices, and language of their texts (category, times) and of the scene variables. |
How to install NWPS River Floods in Gladys
- In Gladys, open Integrations: NWPS River Floods appears in the catalog, next to the native integrations, with a community badge.
- Click Install. Gladys pulls the Docker image (
ghcr.io/guim31/gladys-nwps:1.0.0), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration). - Open the Configuration screen of the integration, fill in the settings, and save.
- You can also install it directly from its repository URL: https://github.com/guim31/gladys-nwps.
NWPS River Floods requires Gladys >=5.3.2. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.
Not running Gladys yet? It is free and open source: follow the installation guide to get started.
About external integrations
NWPS River Floods is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by guim31, not by the Gladys core team.
- Browse all integrations, native and community
- Build and publish your own external integration
- Source code on GitHub — source of this documentation