Find USGS water monitoring sites by bounding box, state, county, or HUC watershed code, filtered by site type and parameter availability. Returns site numbers, names, coordinates, types, altitude, the UTC time each site last reported (lastObservedAt), and (in expanded mode) drainage area. Call this first — water_get_readings, water_get_series, and water_get_conditions all require a site number. Supply exactly one major filter — bbox, stateCd, countyCd, or huc; siteType, parameterCd, hasDataTypeCd, and observedWithin only narrow within it and cannot stand alone. parameterCd and hasDataTypeCd match sites that have ever reported, discontinued ones included; set observedWithin to keep only sites reporting now. Page through matches with limit/offset (500 per page); truncated=true means matches remain after the returned window and upstreamTotal holds the full count. When the match set exceeds 500 and DataCanvas is enabled, the complete set also stages to a canvas (canvas_id/table_name) — inspect it with water_dataframe_describe, then retrieve it with water_dataframe_query.
View input schema
{
"type": "object",
"properties": {
"bbox": {
"description": "Bounding box as \"west,south,east,north\" in decimal degrees (e.g. \"-77.5,38.5,-76.5,39.5\" for the DC metro area). One of the four major filters — bbox, stateCd, countyCd, and huc are mutually exclusive with each other, and exactly one must be supplied.",
"type": "string",
"pattern": "^-?\\d+(\\.\\d+)?(,-?\\d+(\\.\\d+)?){3}$"
},
"stateCd": {
"description": "2-letter US state or territory postal code, any case (e.g. \"VA\", \"wa\", \"PR\"). Returns all sites in the state for the given filters. Major filter — supply exactly one of bbox, stateCd, countyCd, huc.",
"type": "string",
"pattern": "^[A-Za-z]{2}$"
},
"countyCd": {
"description": "FIPS county code(s) as bare 5-digit numbers — state and county digits concatenated, no separator (e.g. \"51013\" for Arlington, VA). Comma-separate up to 20 (e.g. \"51059,51061\"). The 5 digits already encode the state, so the code stands alone. Major filter — supply exactly one of bbox, stateCd, countyCd, huc.",
"type": "string",
"pattern": "^\\d{5}(,\\d{5}){0,19}$"
},
"huc": {
"description": "Hydrologic Unit Code (HUC) scoping results to a watershed: a 2-digit region (e.g. \"02\" for the Mid-Atlantic) or an 8-digit subbasin (e.g. \"02070008\" for the Middle Potomac). Matches every site whose HUC starts with it. Major filter — supply exactly one of bbox, stateCd, countyCd, huc.",
"type": "string",
"pattern": "^(\\d{2}|\\d{8})$"
},
"siteType": {
"description": "Site type filter. Common codes: \"ST\" (stream), \"GW\" (groundwater well), \"LK\" (lake/reservoir), \"SP\" (spring), \"AT\" (atmosphere), \"OC\" (ocean), \"ES\" (estuary). A major type includes its subtypes (\"ST\" also matches \"ST-CA\", \"ST-DCH\", \"ST-TS\"); a subtype matches only itself. Comma-separate multiple types (e.g. \"ST,GW\").",
"type": "string"
},
"parameterCd": {
"description": "5-digit parameter code each returned site has ever reported (e.g. \"00060\" for discharge) — a site whose record ended years ago still matches; read lastObservedAt, or set observedWithin to keep only sites reporting now. Matched against the series hasDataTypeCd selects (continuous, daily, and field-measurement series when it is omitted), never discrete water-quality samples, so a site with only lab-analyzed samples for the code does not match. Use water_list_parameters to discover codes. Comma-separate multiple codes with no spaces (e.g. \"00060,00065\").",
"type": "string",
"pattern": "^\\d{5}(,\\d{5})*$"
},
"hasDataTypeCd": {
"description": "Require sites that have ever reported data of this type: \"iv\" (instantaneous, continuous record; \"uv\" and \"rt\" are aliases), \"dv\" (daily values), \"gw\" (groundwater-level field measurements), \"pk\" (annual peaks). No other code has a source. Comma-separate multiple types. A discontinued site still matches — read lastObservedAt, or set observedWithin to keep only sites reporting now.",
"type": "string"
},
"observedWithin": {
"description": "ISO 8601 duration ending now, the form water_get_readings period takes (e.g. \"P7D\", \"PT6H\", \"P1Y\"). Keeps only sites whose lastObservedAt falls inside it — sites reporting now, not discontinued ones. Counts the series parameterCd and hasDataTypeCd select, or any continuous, daily, or field-measurement series when both are omitted. Daily values and field measurements carry a date only and daily values publish a day or two late, so a window under \"P3D\" can drop a site that reports daily values only.",
"type": "string",
"pattern": "^P(?!$)(\\d+Y)?(\\d+M)?(\\d+W)?(\\d+D)?(T(?=\\d)(\\d+H)?(\\d+M)?(\\d+(\\.\\d+)?S)?)?$"
},
"siteOutput": {
"default": "basic",
"description": "\"basic\" returns core identification fields. \"expanded\" adds drainage area, altitude, contributing area, and other metadata.",
"type": "string",
"enum": [
"basic",
"expanded"
]
},
"limit": {
"default": 500,
"description": "Maximum sites to return inline, 1–500. Default 500 (the inline cap).",
"type": "integer",
"minimum": 1,
"maximum": 500
},
"offset": {
"default": 0,
"description": "Number of matching sites to skip before returning results. Page through matches beyond the inline cap by advancing offset by limit. Default 0.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"canvas_id": {
"description": "Canvas ID from a prior call to add this match set as a table on an existing canvas rather than creating a new one. Each distinct filter set gets its own table name, so re-running the identical query replaces its own table while a different query adds another alongside it. Applies only when the match set exceeds the inline cap and DataCanvas is enabled. Omit to start a fresh canvas.",
"type": "string",
"pattern": "^[A-Za-z0-9_-]{10}$"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}