Data sources & methodology

How LakeLevels dates a reading — not when this page was written

Every number on a lake page is copied from a public feed published by an agency or utility. This page names those feeds, how often we pull them, how seasonal normals are computed from our own archive, and what the numbers cannot say. For a shorter overview see About.

Provenance

Ingest writes each source’s catalog and readings into Postgres. Lake pages then read the stored row — they do not call upstream on every visit. Each lake page links to the operator so you can check the official reading.

• US Geological Survey (USGS) — National Water Information System (NWIS) site inventory and instantaneous / daily values. Lake pages use reservoir elevation (or gage height where that is what the site publishes). A site with only temperature, or a discontinued gage older than the 400-day live window, is not filed as a current lake level. Official site: waterdata.usgs.gov.
• US Army Corps of Engineers (USACE) — Corps Water Management System (CWMS) across district offices. Catalog membership requires a usable observed elevation series; forecast-only traces and river / lock / structure gages are not listed as lakes. Official portal: water.usace.army.mil.
• Bureau of Reclamation — RISE catalog and lake/reservoir elevation (and storage when published). RISE has no bulk levels endpoint, so current elevations are refreshed in hourly slices of about 40 lakes, oldest reading first, across the ~230-lake set. Official API: data.usbr.gov.
• Other public operators— Tennessee Valley Authority, Duke Energy, Alabama Power, Georgia Power, the Texas Water Development Board, and California DWR / CDEC. Each lake page names the operator and links to that operator’s public page.

Update cadence

A scheduled hourly job fetches every source, upserts new readings, and refreshes derived stats. Pages may therefore lag the operator by about an hour (about fifteen minutes on the rare direct-upstream fallback). That lag is caching and ingest timing — not a second clock we invent.

The Last updated stamp on a lake page is the observation time the source published with the reading (currentLevelDate), shown as an absolute timestamp and, after the page hydrates, a relative age. If the source did not publish a usable time, the page says so. It is not the time we last crawled, and it is not the clock on the visitor’s device.

A reading older than two days is labelled stale for every source except Reclamation, whose slice rotation uses an eight-day window so a lake waiting its turn is not marked broken. Stale readings are still shown: an old official number is more honest than pretending there is none.

How seasonal normals are computed

The “near / above / below the N-year median” sentence on some leisure lake pages is computed from LakeLevels’ own readings archive. It is not an operator guide curve and it is not scraped from a recreation pamphlet.

• Hours collapse to one value per UTC day so a recent hourly ingest cannot outweigh an older daily year.
• Each calendar day of the year gets a band from readings in a ±7-day window around that day. 29 February folds onto 28 February so a leap day does not shift the rest of the year.
• The band is the median plus the 10th and 90th percentiles. A sentence is published only when at least three distinct years contribute; the copy states that year count.
• Bands are recomputed about weekly, not hourly, and only for the leisure seed list that has a long enough archive. A miss renders nothing — never a placeholder and never a band invented from a thin history.
• Units follow the lake: feet of elevation, or percentage points on a percent-of-full-pond lake. The compared value is always this page’s current reading.

Two different percentages

Percent full by volume is the share of the water the reservoir holds when full. Elevation vs full pool is a ratio of heights. They are not interchangeable: a reservoir can sit near its full-pool elevation while holding a fraction of its water. Neither figure is shown unless the source publishes what it takes to compute it honestly. When fullness is estimated from a checked-in capacity table rather than measured storage, the page says it is an estimate.

Known limitations

• LakeLevels is not affiliated with, or endorsed by, any agency or utility. Always verify conditions with the official source before making decisions on the water.
• Upstream sometimes ships sentinel or forecast-dated values. Those are rejected at ingest when we can see them, and a stored row that later looks implausible (for example far below the lake’s own published floor) is quarantined rather than deleted.
• Reclamation freshness is slower by design. USGS and USACE catalogs hide discontinued or forecast-only series; a lake that left the catalog is not kept alive with a guessed level.
• Seasonal normals cover only lakes with enough of our own history. Most of the catalog has no normal sentence, and that silence is intentional.
• History charts may be daily for long ranges and finer for short ones. A gap in the archive is a gap, not a flat line we invent.

Contact

Questions or a correction? Email wizkid.blake@gmail.com. The same address is in the footer on every page. See also the About and Privacy pages.