National Water Prediction Service API

What you can build

• Prepare sites ahead of a forecast crest

  When a forecast puts a gauge at minor flood or higher, the operator matches it to the properties you mapped to that gauge and proposes the prep checklist, with the forecast issue time on the proposal.

  With Storm Prep

• Hold shipments through a flooded route

  Routes are tied to gauges. A forecast that crosses the action stage proposes a hold or reroute on the affected stops before dispatch, for your approval.

  With Weather Hold

• Draft the evacuation roster

  A forecast at moderate or major flood for a gauge tied to a site proposes the roster for that site and refreshes it when the forecast is reissued.

  With Evacuation Roster

• Send a rising-water notice

  The operator drafts a notice from the observed stage, the forecast crest, and the flood impact statement for that stage, ready to send to the sites downstream.

  With Severe Weather Notice

Requirements

• The NWS location ids or USGS ids of the gauges near your sites, routes, or intakes
• Your own stage or flow thresholds per site, since flood categories describe the gauge, not your building
• A client that reads UTC timestamps and the per-gauge time zone the API returns
• For ungauged streams, the National Water Model reach id, such as 23021904, from the reach endpoints

Authentication

None is required. The Swagger spec defines a BasicAuth scheme, but no operation demands it and the endpoints answer plain HTTPS requests.

Limits

• No historical archive beyond crest and low water history; observations and forecasts cover the current window only
• Flood categories and forecasts exist only where the NWS issues them; some gauges carry observations without a forecast
• The companion HEFS and NWM APIs are marked experimental, not supported around the clock, and may change without notice
• Ratings return up to 10,000 records per call by default, sorted by stage

Questions and answers

What identifies a gauge?

Either the NWS location id or the USGS site id; the spec's example is ANAW1 or 13334300. The gauge record also carries the National Water Model reach id, the forecast office, the River Forecast Center, state, county, and local time zone.

How are flood categories expressed?

As four thresholds on each gauge: action, minor, moderate, and major, each with a stage value and, where defined, a flow value in the gauge's units. Observed and forecast status report the current category, such as no_flooding, with a validTime.

Does the API cover streams without a gauge?

Partly. The reaches endpoints return National Water Model streamflow for a reach id, by series such as analysis_assimilation, short_range, medium_range, medium_range_blend, and long_range. NOAA states the NWM provides guidance and is not an NWS forecast product.