io.github.Adeniyikayodee/gagelink

Metadata for one monitoring location: its name, position, drainage area, timezone, the vertical datum its stage readings are measured from, and how well that offset is known. Call this before comparing any stage against an elevation, because the answer depends on the offset it returns. Most US stations publish their offset on NGVD29 while modern surveys are on NAVD88; pass on_datum to have the offset converted before you difference anything. Takes a USGS identifier, an Environment Agency one as in EA-2604TH, or a Hub'Eau one as in FR-F700000102.

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.

Search 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. Pass country=FR to search the French network by river name, commune, department, or bbox, or country=GB for the Environment Agency by river, town, or station name.

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.

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.

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. Takes a USGS identifier, an Environment Agency one as in EA-2604TH, or a Hub'Eau one as in FR-F700000102, whose values are published with no unit at all and are labelled here.

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.

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.

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.

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.

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.

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.

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