GWRC Hilltop NZ

Goal

Query Greater Wellington Regional Council's public Hilltop environmental monitoring server for rainfall gauge totals and river/stream levels and flows — the core severe-weather situational data for the Wellington region — through a deterministic read-only CLI with human and JSON output.

Use this when

• A task needs current or recent Wellington-region river or stream levels/flows
• A task needs rainfall totals across the region's gauges over a recent window
• A task needs GWRC monitoring site locations or the measurements a site offers
• A workflow needs machine-readable Hilltop time-series data from a verified council server in the built-in registry; GWRC is the default

Do not use this for

• Official flood or severe weather warnings — gauge data is raw and provisional; warnings come from MetService and civil defence channels
• River water quality (use lawa-nz), tides (use nz-tides-surf), or forecasts
• Any write, subscription, or alerting action

Commands

python3 skills/gwrc-hilltop-nz/scripts/cli.py sites --search "hutt river" --limit 10
python3 skills/gwrc-hilltop-nz/scripts/cli.py sites --measurement Flow --json
python3 skills/gwrc-hilltop-nz/scripts/cli.py measurements --site "Hutt River at Taita Gorge"
python3 skills/gwrc-hilltop-nz/scripts/cli.py latest --site "Hutt River at Taita Gorge" --measurement Flow --json
python3 skills/gwrc-hilltop-nz/scripts/cli.py rainfall --hours 24 --limit 20 --json
python3 skills/gwrc-hilltop-nz/scripts/cli.py rivers --hours 24 --search hutt --json
python3 skills/gwrc-hilltop-nz/scripts/cli.py collections

• sites [--measurement NAME] [--search TEXT] [--limit N] [--json] — monitoring sites with lat/long
• measurements --site NAME [--json] — data sources, labels, copy-pastable request as names, units, and date spans at one site
• latest --site NAME --measurement NAME [--exact-request-as] [--window-hours N] [--json] — most recent observation; a plain label resolves to the freshest matching series. Use --exact-request-as to force literal request as selection when a value such as Stage also collides with a display label.
• rainfall [--hours N] [--search TEXT] [--limit N] [--json] — per-gauge totals over the window, wettest first
• rivers [--hours N] [--search TEXT] [--limit N] [--json] — latest level/flow per site with min/max and rising/falling/steady trend
• collections [--json] — Hilltop collection names
• councils [--json] — verified council Hilltop servers in the registry

All data commands accept --council gwrc|hbrc|marlborough|northland|tasman. Arbitrary endpoints are deliberately rejected; new official council servers must be verified and added to the registry and declared-domain metadata. Collection names differ per council: rainfall/rivers default to GWRC's collections — for another council run collections --council <key> and pass --collection NAME.

Notes

• No API key or login. Data is CC BY 4.0 — attribute "Greater Wellington Regional Council".
• Gauges log every ~5–15 minutes but upload every 2–3 hours: treat "latest" as up to a few hours behind reality, and never as a substitute for official warnings.
• Timestamps are NZ local time exactly as published by the server.
• Sites can expose duplicate labels such as Stage under multiple data sources. measurements prints each exact request as value; latest --measurement Stage selects the matching series with the newest advertised to timestamp and reports both requested_measurement and resolved_measurement in JSON. Add --exact-request-as to select a literal request as value when it also matches a display label.
• rainfall and rivers exclude decommissioned gauges that still answer with years-old data, and report how many were excluded; latest flags such readings with stale: true and their age in hours.
• Keep windows narrow (--hours defaults to 24, max 168) — collection queries fan out across ~100 sites server-side.

Resources

• CLI entrypoint: scripts/cli.py
• Contract test: scripts/test_contract.py; smoke test: scripts/smoke_test.py
• Endpoint discovery, latency, and licence detail: references/source-notes.md