Search USGS monitoring locations by state, county, hydrologic unit, site type, or bounding box. At least one filter is required. Returns identifiers of the form USGS-01646500, which every other tool takes.

Metadata for one monitoring location: its name, position, drainage area, timezone, and the vertical datum its stage readings are measured from. Call this before comparing any stage against an elevation, because the answer depends on the offset it returns.

The most recent value the service holds for each parameter at a location. Latest is not the same as current: the service returns the last value it has for each parameter independently, so one response can carry a discharge from this morning beside a turbidity from years ago. Pass max_age_hours to drop the stale ones. Values arrive with their unit, datum, and whether the record is provisional or approved.

A date range of record, returned as a handle with a summary and a small sample rather than as its points, since a year of 15-minute record is 35,000 values. Use slice_series on the handle to narrow it. Resolution is daily or continuous.

Narrow a series already fetched under a handle and summarise what remains. Costs no request against the hourly allowance.

Annual peak flow record for a location, largest first. A water year can carry more than one peak, so the count of peaks is not the count of years.

Observed and forecast stage from the NOAA National Water Prediction Service, with the flood thresholds that give them meaning. Stages and thresholds here are on the gage's own datum, so they can be differenced against each other and against a gage height, but not against a surveyed elevation without the offset from describe_location. Takes the USGS identifier or the NWS location id.

National Water Model streamflow for the reach a monitoring location sits on. These are modelled values, not measurements: the model covers reaches with no gauge on them, so a figure here may have nothing observed behind it, and it carries no record-quality grade. Series are analysis_assimilation, which looks back, and short_range, medium_range, medium_range_blend, and long_range, which look forward. Not every reach publishes every series.

Water surface elevation measured from orbit by the SWOT mission, for a river reach. Covers reaches no gauge stands on. Elevations are referenced to the EGM2008 geoid, not to a national datum and not to any gage datum, so they cannot be differenced against a stage or a surveyed elevation. A reach identifier is a SWORD river reach id and is not a USGS station number.

Monitoring locations upstream or downstream of a point, following the river rather than a radius. Direction is upstream, upstream_main, downstream, or downstream_diversions, where upstream includes tributaries and upstream_main follows the main stem alone.

The area draining to a point. The area is computed from the delineated boundary rather than published; where a site record also states a drainage area, that figure is surveyed and is the one to quote.

Resolve a parameter code to what it measures, or find a code by name. Readings carry a code and no name, so this is how 00065 becomes gage height.

The record of this session: every request made, every quantity returned, and the library versions. Enough to re-run the work and check the numbers. Call it last when the answer needs to be reproducible.