find_sites
Discover USGS monitoring sites by name, location, or geographic area, returning station numbers for water data queries.
Instructions
Look up USGS station numbers (siteNumber) to pass to
get_instantaneous_values - use this whenever you have a place or river name
("what's the flow of the Chattahoochee in Atlanta") rather than a station
number. Returned siteNumber values vary in length - typically 8 digits,
but 15 for many groundwater/well sites - pass them through to
get_instantaneous_values exactly as returned; do not truncate or pad.
Exactly one major filter is required: sites, stateCd, huc, bBox, or countyCd
same rule and the same named {west, south, east, north} bBox object as get_instantaneous_values.
nameContains filters results CLIENT-SIDE after fetching, not on the
request - the /site/ service silently ignores name-search parameters, so
this NARROWS a major filter's results rather than replacing it, and cannot
be used alone. Matching is case-insensitive (most USGS station names are
uppercase, e.g. "CHATTAHOOCHEE RIVER AT ATLANTA, GA", but not all are), so
match casually.
A broad major filter with no nameContains can return hundreds of sites -
Georgia alone has 544 IV-reporting sites - so pair a broad filter (stateCd,
a wide bBox) with nameContains when looking for a specific place, and
prefer a narrower filter (countyCd, huc) otherwise.
Defaults to hasDataTypeCd:"iv" (only sites that report instantaneous
values), since a site without IV data cannot be used with
get_instantaneous_values. Also defaults to siteStatus:"active", unlike
get_instantaneous_values (which sends no siteStatus default and so returns
readings from ALL sites) - the same major filter can therefore list fewer
sites here than get_instantaneous_values will actually return readings for.
Pass siteStatus:"all" to see inactive/discontinued sites too. Results are
capped at maxSites (default 50, maximum 500); when more match,
truncated:true and totalMatched: show how many were found in total. The
cap keeps the FIRST maxSites in USGS site-number order, which runs roughly
by drainage basin - raising maxSites therefore returns a geographic slice,
not a broader or more relevant sample. Narrow with nameContains or a
tighter major filter instead of raising maxSites.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| huc | No | Hydrologic Unit Codes: either one 2-digit major HUC, or one or more 8-digit HUCs (up to 10 total). At most one 2-digit HUC per request; 8-digit HUCs can be combined freely. | |
| bBox | No | Bounding box in decimal degrees, as named fields (not a positional array) so west/south/east/north cannot be silently transposed. Area (east-west)*(north-south) must be <= 25 square degrees. | |
| sites | No | USGS site numbers, typically 8 digits (e.g. "01646500"), but 15 digits for many groundwater/well sites (e.g. "334207084254801"). Pass them exactly as find_sites returns them; do not truncate or pad. Site-name lookup (e.g. "Potomac River") is not supported directly - use find_sites to resolve a name to a site number first. | |
| stateCd | No | ||
| countyCd | No | 5-digit FIPS county codes (state FIPS + county FIPS), e.g. "24031" for Montgomery County, MD. | |
| maxSites | No | ||
| siteType | No | ||
| siteStatus | No | active | |
| nameContains | No | Case-insensitive substring match against station names, applied CLIENT-SIDE after fetching - the /site/ service silently ignores name-search parameters, so this NARROWS the results of the major filter rather than the request itself. Cannot be used without a major filter. | |
| hasDataTypeCd | No | Only return sites that report this data type. Defaults to "iv" (instantaneous values), since a site with no IV data cannot be used with get_instantaneous_values. | iv |