← clify home · catalogue

waterdata-usgs API for agents (unofficial) — JSON over curl | clify

USGS Water Data for the Nation: find stream, lake and groundwater monitoring locations and fetch their real-time readings, field measurements, time-series metadata, daily statistics, basins and flowlines using the public USGS Water Data APIs.

Host: waterdata.usgs.gov. Call these verified read commands with plain curl; no install, key, or account. Use the public JSON API with plain curl. No install, key, account, or browser is needed. Example: curl 'https://clify-dev.netlify.app/sites.json'. Start with /search?q=weather, then call /abc/COMMAND. Responses are one JSON object. The hosted MCP and GitHub repo are also available.

Commands

search-monitoring-locations

Full-text search for monitoring locations by water body, place name or ID (e.g. 'Potomac River'). Params: q*, api_limit

curl 'https://clify-dev.netlify.app/waterdata-usgs/search-monitoring-locations?q=Potomac+River'

get-monitoring-location

Get summary metadata for one monitoring location: name, coordinates, elevation, drainage area and description. Params: id*

curl 'https://clify-dev.netlify.app/waterdata-usgs/get-monitoring-location'

list-monitoring-locations-in-bbox

List monitoring locations inside a bounding box (the Explore map). Filter by data type, site type, parameter code and recent activity. Params: boundingBox*, dataType, siteTypeCode, usgsPCode, dataCollectedSinceDatetime, pageSize

curl 'https://clify-dev.netlify.app/waterdata-usgs/list-monitoring-locations-in-bbox?boundingBox=-77.60810852050783%2C39.03945298873317%2C-76.92832946777345%2C39.22587043822116&dataType=Continuous+values'

list-time-series

List the time series at a monitoring location: series ID, parameter, period of record and description. Needed for the data and statistics commands. Params: monitoring_location_id*, statistic_id, parameter_code

curl 'https://clify-dev.netlify.app/waterdata-usgs/list-time-series?monitoring_location_id=USGS-01646500'

get-continuous-data

Get continuous (instantaneous, ~15-minute) readings for a time series or for a location and parameter over a recent period. Params: time_series_id, monitoring_location_id, parameter_code, time

curl 'https://clify-dev.netlify.app/waterdata-usgs/get-continuous-data?time_series_id=8a83eb3a3cbc4087b0c201cf07c0c76d&time=P7D'

get-field-measurements

Get manual field measurements (e.g. measured discharge or gage height) at a monitoring location. Params: monitoring_location_id*, parameter_code, time

curl 'https://clify-dev.netlify.app/waterdata-usgs/get-field-measurements?monitoring_location_id=USGS-01646500&parameter_code=00060'

get-daily-normals

Get day-of-year statistics (median, mean, percentiles) for a daily time series, optionally for a calendar-day range. Params: parent_time_series_id*, start_date, end_date, computation_type, approval_status

curl 'https://clify-dev.netlify.app/waterdata-usgs/get-daily-normals?parent_time_series_id=de8e9d3cfb0f465c9282f6a25d6f37ec&start_date=10-18&end_date=10-18'

get-observation-intervals

Get monthly and yearly aggregate statistics (e.g. arithmetic mean per month) for daily time series. Params: parent_time_series_id*, computation_type, approval_status

curl 'https://clify-dev.netlify.app/waterdata-usgs/get-observation-intervals?parent_time_series_id=2cf409b0d9694c01828f5d4ff14586a5'

search-parameter-codes

Find USGS parameter codes whose description contains a keyword, case-insensitive (e.g. 'discharge' → 00060). Params: keyword*

curl 'https://clify-dev.netlify.app/waterdata-usgs/search-parameter-codes'

get-states

Look up US states/territories by FIPS-based ID (e.g. US-24 → MD), or list them all. Params: id

curl 'https://clify-dev.netlify.app/waterdata-usgs/get-states?id=US-24'

get-hydrologic-unit

Get the name of a hydrologic unit (HUC watershed) from its code. Params: huc*

curl 'https://clify-dev.netlify.app/waterdata-usgs/get-hydrologic-unit'

get-flood-stage

Get NWS flood-stage thresholds (action/minor/moderate/major) for a site; returns {} when none are defined. Params: site_number*

curl 'https://clify-dev.netlify.app/waterdata-usgs/get-flood-stage'

get-basin

Get the upstream drainage basin polygon (GeoJSON) for a monitoring location from the NLDI. Params: id*

curl 'https://clify-dev.netlify.app/waterdata-usgs/get-basin'

Get the NHDPlus river flowlines upstream (UM) or downstream (DM) along the main stem from a monitoring location. Params: id*, mode*, distance

curl 'https://clify-dev.netlify.app/waterdata-usgs/navigate-flowlines?distance=322'

list-states

List the states and territories of a country, with their browse URLs (the state codes are FIPS). Params: country*

curl 'https://clify-dev.netlify.app/waterdata-usgs/list-states'

list-counties

List the counties in a state, with their browse URLs (the county codes are FIPS). Params: state_code*

curl 'https://clify-dev.netlify.app/waterdata-usgs/list-counties'

list-county-monitoring-locations

List every monitoring location in a county, by name and ID. Params: state_code*, county_code*

curl 'https://clify-dev.netlify.app/waterdata-usgs/list-county-monitoring-locations'