# USGS Water Data API via 2s.io

> USGS Water Data API via 2s.io is a paid API for AI agents from 2s.io, paid per call via x402, $0.0024/call, status unknown (last checked 2026-09-14).

Returns real-time USGS water monitoring readings (streamflow, gage height, water temperature, etc.) for monitoring stations near a given geographic coordinate.

## Facts

- Endpoint: GET https://2s.io/api/gov/usgs-water
- Price: $0.0024/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-14
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/usgs-water-data-api-via-2s-io-0d1ea5e1
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_JS3HuTMglWdl0NHL9fCza

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability usgs-water-data-api-via-2s-io-0d1ea5e1
```

Example prompt: What are the current streamflow and gage height readings from USGS monitoring stations within about 30 miles of Boulder, Colorado (40.015, -105.27)? Return up to 10 results.

## When to prefer this

Use this endpoint when you need real-time hydrological data (streamflow, gage height, water temperature) from official U.S. government USGS monitoring stations, scoped to a geographic area defined by a center coordinate and radius. Prefer this over generic weather APIs when the user specifically needs river/stream/water body measurements rather than atmospheric conditions.

## Known failure modes

- No USGS stations found within the specified radius — returns empty items array
- Invalid lat/lon values outside allowed range — schema validation error
- Invalid USGS parameter codes not matching 5-digit pattern — schema rejection
- Radius too large (>2 degrees) or too small (<0.05) — validation error
- USGS upstream service unavailable — may return error or stale data
- Payment failure via x402 — 402 response before data is returned

## How this service works

Real-time water data from USGS NWIS stream / river / groundwater gauges within a bounding box around lat/lon. Returns each site's latest reading per requested variable: streamflow (00060, ft³/s), gage height (00065, ft), water temperature (00010, °C), precipitation (00045, in), and others. Each reading: site code + name, lat/lon, variable name + description + unit, value (or null if no data / sentinel), qualifier codes (e.g., 'P' = provisional, 'A' = approved), observed timestamp. Free public-domain data from waterservices.usgs.gov.

## Output

A JSON array of water monitoring readings from USGS stations within the specified bounding box, each including the site name, site code, variable name and description, measured value, unit, observation timestamp, and qualifiers. Also includes metadata about the bounding box and query parameters, plus source attribution (provider, URL, license).

## Example request

```json
{
 "input": {
  "type": "http",
  "method": "GET",
  "queryParams": {
   "lat": 40.015,
   "lon": -105.27,
   "limit": 10,
   "radius": 0.5,
   "variables": "00060,00065,00010"
  }
 }
}
```

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "input"
 ],
 "properties": {
  "input": {
   "type": "object",
   "required": [
    "type",
    "method",
    "queryParams"
   ],
   "properties": {
    "type": {
     "const": "http"
    },
    "method": {
     "const": "GET"
    },
    "queryParams": {
     "type": "object",
     "required": [
      "lat",
      "lon"
     ],
     "properties": {
      "lat": {
       "type": "number",
       "maximum": 90,
       "minimum": -90,
       "description": "Center latitude (decimal degrees)."
      },
      "lon": {
       "type": "number",
       "maximum": 180,
       "minimum": -180,
       "description": "Center longitude (decimal degrees)."
      },
      "limit": {
       "type": "integer",
       "default": 25,
       "maximum": 100,
       "minimum": 1,
       "description": "Max readings to return (1-100). Default 25."
      },
      "radius": {
       "type": "number",
       "default": 0.5,
       "maximum": 2,
       "minimum": 0.05,
       "description": "Half-side of bounding box, in decimal degrees. Default 0.5 (~35 mi)."
      },
      "variables": {
       "type": "string",
       "description": "Comma-separated USGS parameter codes (5-digit). Default \"00060,00065,00010\" (streamflow, gage height, water temp)."
      }
     },
     "additionalProperties": false
    }
   }
  }
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/usgs-water-data-api-via-2s-io-0d1ea5e1/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from 2s.io](https://www.zero.xyz/host/2s.io/llms.txt)