WaterLevels.org
Data disclosures

How we use agency water data

WaterLevels.org is an independent site that republishes selected public water monitoring data from the U.S. Geological Survey, curated reservoir elevations from the U.S. Bureau of Reclamation (RISE), the U.S. Army Corps of Engineers (CWMS), and the California Data Exchange Center (CDEC), selected National Weather Service NWPS gauges without a USGS site id, plus flood categories and stage thresholds from NWPS when available. This page explains where that data comes from, what we keep, how we use it, and what it is not. It also covers the information we collect from you when you search, center the map, or subscribe to email alerts.

Data sources

Nearly all stream and lake observation values shown on WaterLevels.org come from the USGS Water Data APIs (OGC API–Features services operated by the USGS). Site identity, coordinates, and official station pages for those gauges are likewise USGS products.

Selected Reclamation reservoirs (for example Lake Mead at Hoover Dam) use daily lake/reservoir elevation from the Bureau of Reclamation RISE APIs. Those stations are identified separately from USGS gauges and link to the official RISE location page for provenance and datum notes.

Selected Corps reservoirs and pools (for example Raystown Lake, Hartwell Dam, and Lake Okeechobee) use lake/reservoir elevation from the U.S. Army Corps of Engineers CWMS Data API. We curate Corps-owned series and skip USGS-revision mirrors published in CWMS. USACE pages do not use NWPS flood stages.

Selected National Weather Service NWPS gauges that publish no USGS site id (for example Alpowa Creek at Mouth) appear as first-class stations with observed stage from the NWPS API. We do not promote NWPS points that already join to a USGS gauge (those stay USGS stations with NWPS flood enrichment only), and we skip lids that would duplicate reservoirs already ingested from USBR.

Selected California reservoirs that USBR and USACE do not already cover (for example Lake Oroville, Lake Shasta, and Folsom Lake) use daily lake/reservoir elevation from the California Data Exchange Center. Shasta is USBR-operated, but it is not on the USBR RISE allowlist, so CDEC is the source. CDEC pages do not use NWPS flood stages.

Flood categories (action, minor, moderate, major) and stage thresholds, when shown on the map, Flood Alerts list, and station pages, come from the National Weather Service National Water Prediction Service (NWPS) via the NWPS API. We join NWPS forecast points to USGS gauges by site number when a match exists. Not every USGS site has an NWPS forecast point, so some stations will show USGS measurements without flood-stage context. USBR, USACE, and CDEC reservoir pages do not use NWPS flood stages. We do not chart NWPS forecast hydrographs. A forecast category can still raise the stored flood category used by the map and Flood Alerts list, described below. Station pages do not treat that forecast as the current flood stage.

Upstream and downstream neighbors on USGS station pages come from the USGS Network Linked Data Index (NLDI). We ask NLDI which NWIS sites lie along the flowpath within about 80 kilometers, then keep the closest matches we already index. Nearby stations are not an agency product: we compute them from the coordinates stored with each gauge.

USGS, USBR, USACE, and NWS products are U.S. government work. CDEC products are California state government work, operated by the California Department of Water Resources. WaterLevels.org is a personal project by Johnathan Lyman. It is not affiliated with, endorsed by, or operated by the USGS, the Bureau of Reclamation, the U.S. Army Corps of Engineers, the National Weather Service, NOAA, the Department of the Interior, the Department of Defense, or the California Department of Water Resources. It consumes public APIs and presents a subset of that data for browsing and reference.

For the authoritative hydrologic record at any station, use the official agency page linked from that WaterLevels.org station: typically waterdata.usgs.gov for USGS, data.usbr.gov for Reclamation, the CWMS location page for Corps projects, cdec.water.ca.gov for California reservoirs, and water.noaa.gov for NWPS-only gauges. For official flood forecasts, impacts, and watches/warnings, use water.noaa.gov and local NWS products. Official pages may include additional parameters, cooperators, remarks, and quality notes that we do not show.

What we show

We focus on surface-water sites that currently report at least one of:

  • Water level / stage — including gage height (USGS parameter code 00065) and, where available, lake or reservoir elevation relative to a vertical datum such as NGVD 1929 (62614) or NAVD 1988 (62615), or height above a local datum (00062).
  • Streamflow / discharge — USGS parameter code 00060, typically in cubic feet per second.
  • Water temperature — USGS parameter code 00010, stored in Celsius and convertible to Fahrenheit in the interface.
  • Reservoir elevation — daily or pool elevation for a curated allowlist of USBR, USACE, and CDEC reservoirs (CDEC sensor 6). These are not USGS parameter codes, and we do not ingest every reservoir or series those agencies publish.
  • NWPS observed stage — gage height from recent NWPS stageflow observations for gauges we promote that have no USGS site id. That history is typically about 30 days. We do not store the forecast portion of stageflow.
  • NWS flood context — action, minor, moderate, and major stage thresholds from NWPS when a gauge is matched, plus a flood category. The category we store is the more severe of the NWPS observed category and the NWPS forecast category when both are present. It colors the map and fills the Flood Alerts list. Station pages compare the current gage height with those thresholds: they name the flood stage the river is in, and when it is below flood stage they give the lowest flood-stage level. USBR, USACE, and CDEC pages omit it.
  • Neighbors — upstream and downstream USGS gauges from NLDI, and nearby gauges ranked by distance between stored coordinates.

When a USGS site reports more than one water-level style parameter, we generally prefer gage height for map and default display, and still expose the other selected series on the station page so you can compare them. We do not attempt to host the full USGS groundwater-well archive, every historical field measurement, or the full parameter catalogs of USBR, USACE, CDEC, or NWPS.

How the data is used

In practical terms, WaterLevels.org:

  • Discovers active USGS sites from latest-continuous feeds for the parameter codes above, and stores monitoring-location metadata (name, site number, coordinates, state and county, and drainage area or hydrologic unit when the feed includes them) plus selected time-series metadata.
  • Refreshes a curated allowlist of USBR, USACE, CDEC, and NWPS-only gauges from those agencies’ APIs. Stations outside the allowlist are not added.
  • Caches the latest observation for map popups, station current conditions, the Flood Alerts list, and optional email alerts.
  • Syncs NWPS flood categories and stage thresholds for matched gauges. The stored category is the more severe of the observed and forecast categories. It appears on the map and the Flood Alerts list, and it can trigger flood emails for people who opted in. Station pages report the stage implied by the current gage height, including the lowest flood-stage level when the river is not at flood stage.
  • Backfills USGS continuous history (about 35 days), daily values, and peak series where USGS publishes them, and keeps longer daily history so charts and tables render from our cache: about three years for USGS, and up to about ten years for curated USBR, USACE, and CDEC reservoirs. When USGS does not publish a daily value, a chart may show an estimated daily mean computed from stored continuous readings and labeled as estimated.
  • Stores recent observed NWPS stageflow points for short charts on NWPS-only gauges. NWPS does not provide the long daily archive used for the reservoir sources.
  • Uses USGS NLDI to attach upstream and downstream neighbors, and computes nearby stations from stored coordinates.
  • Uses those stored readings to send optional email alerts and daily digests (water level, discharge, flood category, and related threshold rules) to confirmed subscribers. Those messages are informational. They are not NWS watches or warnings.
  • Serves highly cached HTML and JSON responses so the site stays fast; cached pages can lag behind the live agency feeds by design.

We do not sell agency observations, resell raw API access, or claim ownership of those observations. Values are shown for informational browsing. Units, parameter descriptions, approval status, and timestamps are taken from the source fields when present.

Provisional data and limitations

USGS marks many real-time values as provisional. Provisional data can be revised, corrected, or removed after USGS review. Approved values are more stable but still subject to USGS publication practices. USBR, USACE, and CDEC elevations can also be revised by those agencies. NWPS observed stage that we store is treated as provisional because NWPS can update it. Flood categories and thresholds can change as conditions and forecasts update, including when a forecast category is more severe than the observed category.

WaterLevels.org is not a warning system and is not suitable as the sole source for flood response, navigation, engineering design, legal disputes, or other safety-critical decisions. Always confirm against the official agency page for that station and local emergency authorities when those decisions matter.

Gaps can appear when a sensor is offline, a parameter is discontinued, our sync lags, a station falls outside the site types or allowlists we keep, an NWPS or NLDI match is missing, or an agency rate limit or API error interrupts a refresh. “Stale” labels on the site mean our latest stored observation is older than our freshness threshold (currently one week), not necessarily that the source agency has stopped collecting data.

Updates and caching

Catalog, latest-observation, reservoir, NWPS-gauge, and flood-stage syncs run on a schedule (and can be triggered operationally). Station history is filled on demand and by batch jobs. Longer daily history is kept in an archive so year-scale charts do not depend on a live agency call. Public pages and map station payloads are cached at the application and, in production, often at the CDN edge. That means the number or flood category you see may be minutes to hours behind the source agency at peak, and occasionally longer if a sync has not completed.

Attribution

Hydrologic observation data: U.S. Geological Survey. Access via the USGS Water Data APIs (api.waterdata.usgs.gov). Prefer citing the specific monitoring location and observation time when you reuse a value from this site.

Flood categories and stage thresholds: National Weather Service, National Water Prediction Service (water.noaa.gov; API api.water.noaa.gov/nwps). Prefer citing the NWPS gauge (LID) and valid time when you reuse a flood-stage value from this site.

Reclamation reservoir elevation: U.S. Bureau of Reclamation, RISE (data.usbr.gov). Prefer citing the RISE location and observation date.

Corps reservoir elevation: U.S. Army Corps of Engineers, CWMS Data API (cwms-data.usace.army.mil). Prefer citing the CWMS office, location, and timeseries.

California reservoir elevation: California Department of Water Resources, California Data Exchange Center (cdec.water.ca.gov). Prefer citing the CDEC station id, sensor, and observation date.

Upstream and downstream relationships: U.S. Geological Survey, Network Linked Data Index (api.water.usgs.gov/nldi).

The interactive map uses CARTO Dark Matter vector basemaps, built on OpenStreetMap data; map credit appears in the map control itself. Your browser loads those tiles from CARTO.

ZIP code search uses Zippopotam.us to turn a U.S. ZIP code into a place name and map point.

Information from your visit

Browsing the map, directories, and station pages does not require an account. We still handle a few kinds of information so search, location, and optional email alerts work:

  • ZIP code search — if you search with a U.S. ZIP code, we send that ZIP to Zippopotam.us, cache the returned place and centroid for about 30 days, and use it only to open the map near that place. We do not attach the ZIP to an account.
  • Device location — “Use my location” runs only after you choose it. The browser sends coordinates to our nearest-station lookup so we can center the map or open a nearby gauge. We do not store those coordinates as a profile.
  • Email alerts — if you subscribe, we store your email address, time zone, digest schedule, quiet hours, the stations you watch, and the alert rules you set. We use the cached water readings and flood categories described above to send confirmation, threshold, flood, and digest messages. Delivery goes through our email provider. You can pause or unsubscribe from any alert email or the manage page.
  • Contact form — name, email, subject, and message are emailed to us so we can reply. A Cloudflare Turnstile check runs on that form, on alert signup, and when you request a manage link, to reject automated submissions.

Server logs, analytics, and error reports are covered in the privacy policy, including Cloudflare, Fathom Analytics, Sentry, and Bento. That policy is the place for how long we keep personal information and the choices you have.

Questions about a value

If something looks wrong on WaterLevels.org, first check the official agency page linked from the station for hydrologic values, or NWPS for flood category and stage thresholds. If the official source and this site disagree, treat the official source as correct and contact us with the site number and approximate time so we can investigate our sync or display logic.