get_instantaneous_values
Retrieve real-time and recent USGS streamflow, gage height, and water temperature readings from USGS gauges, filtered by site, state, HUC, bounding box, or county.
Instructions
Query the USGS Instantaneous Values (IV) service for real-time and recent surface-water and groundwater readings (streamflow, gage height, water temperature, etc). Data is available from 2007-10-01 onward.
Exactly one major filter is required to scope the query: sites, stateCd, huc,
bBox, or countyCd. Providing zero, or more than one, is rejected. sites
are USGS station numbers, typically 8 digits but 15 digits for many
groundwater/well sites - pass them exactly as find_sites returns them, do
not truncate or pad. Looking up a site by name (e.g. "Potomac River") is
not supported by this tool; call find_sites first to resolve a name to a
station number. bBox is an object
{west, south, east, north} in decimal degrees - west/east are longitude
(negative in the continental US), south/north are latitude (positive in the
continental US) - with area (east-west)*(north-south) capped at 25 square
degrees.
Date range: use either period (an ISO-8601 duration, e.g. P7D for the last
7 days) OR startDT/endDT for an absolute range - never both. endDT
requires startDT. A query - dated or not - can return readings that are
years old: a latest-value query returns the latest reading PER SENSOR,
including sensors quietly gone dormant or decommissioned years ago, and a
dated range can end early for one sensor while its siblings keep reporting
through the end of the window. Every series carries stale, which is
TRI-STATE, not a plain boolean: true (latest reading is more than 48 hours
behind the query's reference time), false (it is not), or null (staleness
could not be evaluated - no resolvable reference time, or no readings at
all). Treat null as "not verified", never as current - check stale before
reporting ANY value as current. discontinued explains WHY when USGS says
so in the sensor's method description, but is not itself the signal to
check - a sensor can go stale with no marker at all. When any returned
series is stale or unevaluable, the response includes a note naming which
ones, their reading dates, and how far behind they are.
This tool sends no siteStatus default, so USGS returns readings from ALL
sites regardless of status - unlike find_sites, which defaults to
siteStatus:"active". The same major filter can therefore return readings
from sites find_sites didn't list. This is unrelated to stale/discontinued:
a stale or decommissioned sensor sits at an otherwise-active site, so no
siteStatus value filters it out.
Use mode:"summary" (not the default "values") for any window longer than a
day. It returns {count, nonNullCount, min, max, mean, first, last} per series
instead of every reading, avoiding truncation. mode:"values" returns up to
maxValues (default 200, maximum 1000) of the MOST RECENT readings PER
SERIES and sets truncated:true when more exist - a site with two sensors
for the same parameter returns two series, each capped independently, so a
2-sensor site can still ship up to 2x maxValues readings total.
checkResponseSize backstops the overall payload regardless. A single site
over a single year already returns roughly 35,000 readings per series -
windows beyond about a year should always use mode:"summary".
Returned values may be provisional (qualifier code "P") and subject to revision - present them as such, not as final measurements.
A series is omitted entirely, with no placeholder, when a site does not
measure a requested parameter - a query for 3 parameterCd values can return
fewer than 3 series. Match results on each series' variable.code; do not
assume series[i] corresponds to parameterCd[i]. When this happens the
result includes missingParameterCodes.
Don't know the 5-digit parameter code for what you want? Call list_common_parameter_codes first.
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. | |
| mode | No | values | |
| endDT | No | ||
| 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. | |
| period | No | ISO-8601 duration for a relative window ending now, e.g. "P7D" for the last 7 days or "PT6H" for the last 6 hours. Cannot be combined with startDT/endDT. | |
| startDT | No | ||
| stateCd | No | ||
| agencyCd | No | ||
| countyCd | No | 5-digit FIPS county codes (state FIPS + county FIPS), e.g. "24031" for Montgomery County, MD. | |
| siteType | No | ||
| maxValues | No | ||
| siteStatus | No | ||
| parameterCd | No | ||
| modifiedSince | No |