gwrc-hilltop-nz
Query Greater Wellington Regional Council Hilltop environmental monitoring time series through a lightweight no-login CLI: rainfall gauges, river and stream levels and flows, monitoring site lists wit
SKILL.mdskills/gwrc-hilltop-nz/SKILL.md
GitHubGWRC 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 (usenz-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/longmeasurements --site NAME [--json]— data sources, labels, copy-pastablerequest asnames, units, and date spans at one sitelatest --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-asto force literalrequest asselection when a value such asStagealso collides with a display label.rainfall [--hours N] [--search TEXT] [--limit N] [--json]— per-gauge totals over the window, wettest firstrivers [--hours N] [--search TEXT] [--limit N] [--json]— latest level/flow per site with min/max and rising/falling/steady trendcollections [--json]— Hilltop collection namescouncils [--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
Stageunder multiple data sources.measurementsprints each exactrequest asvalue;latest --measurement Stageselects the matching series with the newest advertisedtotimestamp and reports bothrequested_measurementandresolved_measurementin JSON. Add--exact-request-asto select a literalrequest asvalue when it also matches a display label. rainfallandriversexclude decommissioned gauges that still answer with years-old data, and report how many were excluded;latestflags such readings withstale: trueand their age in hours.- Keep windows narrow (
--hoursdefaults 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