River Pulse

The problem

The old front door is closing

For years, apps read USGS stream gauges from a service called Water Services, and USGS has announced it will be retired in the first quarter of 2027. The replacement, the Water Data API, is public and open to a browser. The hard part is what it does to you the first time: the latest reading can be decades old, a reading does not carry its gauge's name, and one filter returns a success with nothing in it.

Watch it work

Episode 4 — River Pulse (5:40)

One public API end to end: where the gauge data lives now, the request the app actually makes, the three details that cost the most time, and the map they turn into.

What it covers

One API, three details, one map

• The request: one call to the latest-continuous collection asks for two measurements at once — river flow (parameter 00060) and river height (00065). Every response is GeoJSON, following the OGC API – Features standard, with open headers so a browser can call it directly.
• Detail one, the latest reading is not always recent: the collection returns the last value each gauge ever sent. On the day the episode was recorded, Colorado returned 635 gauges, only 339 had reported in the last seven days, and the oldest “latest” reading was from 1987. River Pulse keeps only gauges heard from in seven days, and says how many went quiet.
• Detail two, readings with no name: each value arrives with an identifier, a timestamp and a location, but no gauge name. Names live in the monitoring-locations collection and are joined on the identifier, which now starts with USGS and a dash. The value itself arrives as text and is converted to a number first.
• Detail three, a filter that fails without an error: parameter codes accept a list, but site_type_code=ST,LK answers HTTP 200 with zero gauges. River Pulse asks for everything in the state and filters on its own side.
• Rate limits: anonymous traffic is limited to a number USGS does not publish, and the answer at the limit is HTTP 429. River Pulse keeps the last good data on screen and tries again on the next refresh.
• How it becomes a map: each gauge is colored on a log scale by where its flow sits against the state median. Select one and the card shows a seven-day hydrograph, one reading every fifteen minutes. Every five minutes the state refreshes quietly and your selection stays where it was.

What it does not do

• No history beyond a week — River Pulse charts the last seven days, not the long-term record.
• No retired gauges — gauges silent for more than seven days are counted, not drawn.
• Not a flood warning service — it shows public USGS readings. For flood safety decisions, follow your local National Weather Service office.

Where the data comes from

Every source in the episode

• USGS Water Data API (OGC API – Features) — api.waterdata.usgs.gov/docs/ogcapi/
• Water Data API keys and rate limits — api.waterdata.usgs.gov/docs/ogcapi/keys/
• USGS: Water Services decommission — waterdata.usgs.gov/blog/api-waterservices-decom/
• USGS: acknowledging or crediting USGS — usgs.gov/information-policies-and-instructions/acknowledging-or-crediting-usgs
• Source sheet with every endpoint — allthingsspatial.io/pages/sources.html

USGS water data is in the public domain, as a work of the United States government, and USGS asks to be credited, so attribution sits in the River Pulse footer and its About dialog.