gagelink

Hydrology data for AI agents. River level, streamflow, flood forecasts, water quality, drainage basins, and satellite water surface elevation, from USGS, NOAA, Hub'Eau, the UK Environment Agency, and SWOT. Every value carries its unit, the datum it is measured from, its timezone, and whether the record is provisional or approved.

mcp-name: io.github.Adeniyikayodee/gagelink

Pre-alpha. The API will change.

Run it as an MCP server

{
  "mcpServers": {
    "gagelink": {
      "command": "uvx",
      "args": ["--from", "gagelink", "gagelink-mcp"]
    }
  }
}

No account is needed to start. A free key from api.waterdata.usgs.gov/signup raises the allowance from 50 requests an hour to 1,000; set it as GAGELINK_API_KEY.

Or as a library:

pip install gagelink

Questions it answers

• How high is the river at a gage, and how does that compare with flood stage?
• How much freeboard is there between the water and a surveyed levee crest?
• What is the discharge now, and what fraction of the record peak is that?
• What is forecast over the next few days, and does it cross a flood category?
• What lies upstream or downstream of this point, along the river?
• How large is the basin draining to this point?
• What did this station record over a date range, and has that record been revised since?
• What is the water surface elevation of a river with no gage on it?
• Is a reading provisional or approved, and how old is it?

What it refuses, and why that is the point

A gage height is measured from the station's own datum, not from sea level. Subtracting one from a surveyed elevation returns a number that looks like a freeboard and is wrong by tens of feet, in the direction of calling a levee safe. Both figures are lengths in feet, so nothing dimensional separates them and no units library catches it.

This package refuses that subtraction rather than answering it, and describe_location returns the offset that makes it well defined. The same applies to satellite elevations, which are on a geoid, and to modelled flows, which may have no measurement behind them.

Why

Water services already publish everything needed to use their data correctly. A discharge states its unit, a stage states the datum it is measured from, a reading states whether it is provisional or approved, and a timestamp states its offset. Clients typically parse the number and drop the rest, and the errors follow from that.

The failure is measurable. In a benchmark of 4,288 runs across eleven models, quantity-guard found that every model reaching the computing tool sent a discharge published in cubic feet per second into a parameter declared in cubic metres per second without converting it, on nearly every run, giving an answer 35.3 times too large with nothing in the output to indicate it. Seven of eleven differenced a stage on a local gage datum against an elevation on NAVD88 and reported the result as freeboard.

gagelink retrieves the data with the metadata kept, and uses quantity-guard to enforce it where the agent's tools are called.

Current surface

from gagelink import Service

service = Service(api_key="...")           # free key, see below
page, retrieval = service.items(
    "latest-continuous",
    monitoring_location_id="USGS-07374000",
    parameter_code="00060",
)

retrieval.record()      # what a replay needs: url, params, time, status, sha256
retrieval.quota         # Quota(limit=1000, remaining=999)

items returns the parsed page and the record of having fetched it together, rather than the page alone, because a number that reaches an answer without the request that produced it cannot be replayed, and pairing them at the only entry point is cheaper than remembering to record it.

Payloads become quantities that carry their own reference frames:

from gagelink import location_from, readings_from

page, _ = service.items("monitoring-locations", id="USGS-06730500")
station = location_from(page["features"][0])
station.register()                       # its datum, and the offset where one is published

observations, _ = service.items("latest-continuous", monitoring_location_id=station.id)
readings = {r.parameter_code: r for r in readings_from(observations, station)}

readings["00060"].value       # Q(1.35 ft³/s (provisional))
readings["00065"].value       # Q(9.11 ft (GAGE:06730500, provisional))
readings["00065"].value.to_datum("NGVD29")   # Q(4869.11 ft (NGVD29, provisional))
readings["00065"].value.to_datum("NAVD88")   # DatumConversionUnavailable

That last line is the point. Boulder Creek publishes its altitude on NGVD29, so a stage there resolves onto NGVD29 and refuses NAVD88, since the offset between the two varies with location and is not published here. Assuming the modern datum because it is the modern datum is a freeboard error one step earlier than the one anybody looks for.

What is not published, and what is done about it

altitude and drainage_area come back as bare numbers, and the collection schema states no unit for either, so the USGS conventions of feet and square miles are applied in normalise.py where they are visible rather than assumed further downstream.

A unit with no mapping is refused rather than guessed. A unit that pint can parse but that this package has no entry for is allowed through with a warning, because parseable is not the same as understood: ppt reads as parts per trillion to pint and means parts per thousand to USGS, which is a factor of 10^9 between two dimensionally identical readings.

A missing value is null here rather than the -999999 that WaterServices published, and it stays missing. The qualifier says why, ["EQUIP"] for an equipment outage.

Approval arrives as Provisional or Approved rather than as P or A, and condition codes grade below their review status, so approved record of an ice-affected measurement grades as unverified rather than as approved.

The station timezone is resolved from the abbreviation together with the daylight saving flag, since MST without daylight saving is Arizona and MST with it is Colorado, and they differ by an hour for eight months of the year.

Tools

A session holds the state for one question and the record of what answered it. Tools return a result rather than raising, because a failure carrying a repair keeps a model in the conversation where it can correct itself, and a raised exception ends the turn.

from gagelink import Session, Toolkit

with Session(question="How high is the Potomac at Little Falls?") as work:
    kit = Toolkit(work)
    kit.describe_location("USGS-01646500")
    kit.get_latest("USGS-01646500", parameters=["00060", "00065"], max_age_hours=6)

    work.audit("The gage height is 3.02 ft and the discharge is 2960 ft3/s.")
    work.manifest()

Every value leaves with its frame attached, and every one is entered in a ledger, so an answer can be checked against what was actually retrieved:

[ok]         3.02 ft        from get_latest.00065
[ok]         2960 ft3/s     from get_latest.00060
[UNSOURCED]  116000 ft3/s   no tool output produced this value

The third line is the check earning its place. The figure is a plausible discharge for that river, it is wrong, and nothing about the sentence containing it indicates as much.

A series is returned as a handle with a summary and a twenty-point sample rather than as its points, since a year of 15-minute record is 35,000 values. The handle is derived from the query that produced it, so a replay of the same session produces the same handle. Results are budgeted, and anything dropped to stay inside the budget is stated in the result, since a silent truncation reads as coverage.

As an MCP server

export GAGELINK_API_KEY=...        # free, see below
gagelink-mcp

{"mcpServers": {"gagelink": {"command": "gagelink-mcp"}}}

Thirteen tools, organised by verb rather than by agency; the server picks the service. All thirteen are read-only and annotated as such, so a client prompts once, not thirteen times.

Results come back as text and as structuredContent against the tool's outputSchema, so a unit, datum or grade is a field rather than a string to re-parse.

Streamable HTTP, for clients that cannot spawn a process:

gagelink-mcp --http                 # http://127.0.0.1:8765/mcp

Loopback, Origin checked, one session and toolkit per conversation. No authentication — --host on a reachable interface gives away your hourly allowance.

The tool descriptions are part of the product rather than documentation of it. In the quantity-guard evaluation, declaring physical metadata in the schema without enforcing it still recovered a third of the runs that failed at baseline, so what a description says about datums, units, and provisional record does work before any validation runs.

Read the full README on GitHub →