USGS Water IV Fetch

Core Goal

• Fetch USGS Water Services iv data for one bounding box or explicit site list.
• Keep the call atomic: one request, one structured JSON payload, no follow-up site-discovery chain required.
• Return site metadata plus flattened time-series records that downstream normalization can map into hydrology observations.
• Keep runtime deterministic with retries, throttling, response-size caps, and validation summaries.

Repository Policy

• This is the canonical USGS station-hydrology skill in this repository.
• When eco-council or OpenClaw assigns a raw artifact path, write this skill's full JSON payload to that exact path with --output.
• Do not treat dry-run output as collected evidence.

Required Environment

• Configure runtime by environment variables in references/env.md.
• Start from assets/config.example.env.
• Load env values before running commands:

set -a
source assets/config.example.env
set +a

Workflow

1. Validate effective configuration.

python3 scripts/usgs_water_iv_fetch.py check-config --pretty

2. Dry-run the query plan first.

python3 scripts/usgs_water_iv_fetch.py fetch \
  --bbox=-77.3,38.8,-77.0,39.1 \
  --period P1D \
  --parameter-code 00060 \
  --parameter-code 00065 \
  --site-type ST \
  --site-status active \
  --dry-run \
  --pretty

3. Run one time-window fetch and write the payload.

python3 scripts/usgs_water_iv_fetch.py fetch \
  --bbox=-77.3,38.8,-77.0,39.1 \
  --start-datetime 2026-03-21T00:00:00Z \
  --end-datetime 2026-03-22T23:59:59Z \
  --parameter-code 00060 \
  --parameter-code 00065 \
  --site-type ST \
  --site-status active \
  --output ./data/usgs-water-iv.json \
  --pretty

4. Optional explicit-site fetch when the mission already knows site numbers.

python3 scripts/usgs_water_iv_fetch.py fetch \
  --site 01646500 \
  --site 01646000 \
  --period P1D \
  --parameter-code 00060 \
  --parameter-code 00065 \
  --output ./data/usgs-water-iv-sites.json \
  --pretty

Output Record Shape

Each item in records is one site-parameter-timestamp observation with fields:

• site_number, site_name, agency_code
• site_type, state_code, county_code, huc_code
• latitude, longitude
• parameter_code, variable_name, variable_description, unit
• observed_at_utc, value
• qualifiers, provisional
• source_query_url

Scope Boundaries

• This skill targets the USGS Water Services Instantaneous Values endpoint only.
• This skill does not infer flood thresholds, return periods, or policy meaning.
• This skill does not geocode place names.
• This skill does not need an API key.
• This skill supports file:// base URLs for deterministic local fixture testing.

References

• references/env.md
• references/usgs-water-iv-api-notes.md
• references/usgs-water-iv-limitations.md
• references/openclaw-chaining-templates.md

Script

• scripts/usgs_water_iv_fetch.py