nz-buses
Query Wellington-region Metlink bus data through a lightweight read-only CLI for stops, routes, arrivals, service alerts, and vehicle positions. Use for Wellington buses only; do not use for Wellingto
SKILL.mdskills/nz-buses/SKILL.md
GitHubNZ Buses
Goal
Query live Wellington-region bus data through a small deterministic CLI with human-readable and JSON output.
Metlink Wellington is the v1 source. This skill intentionally filters the shared Metlink GTFS and GTFS-Realtime feeds to bus routes only.
Use this when
- A user asks about Wellington region Metlink buses
- A user asks for live Metlink bus arrivals from a known stop
- A user wants to search Wellington region stops or routes
- A user asks about Metlink bus service alerts or live bus vehicle positions
- A workflow needs lightweight machine-readable Wellington bus data
Do not use this for
- Auckland buses, trains, or ferries; use
at-transportinstead - Wellington trains or other rail-specific tasks; use a train-specific skill if available
- Wellington ferries or cable car; they are separate modes and are not covered here
- Journey planning, route directions, fares, tickets, or account actions
- Historical timetable claims or punctuality analysis unless another dataset provides history
- High-volume mirroring of Metlink data
Preferred workflow
- Confirm the request is for Wellington-region Metlink buses
- Run
scripts/cli.pywith the narrowest subcommand that answers the task - Use
stops --queryorstops --nearto find stop IDs before callingarrivals - Use
routesorroute <number>to discover route IDs before route-filtered vehicle lookups - Use
--jsonfor agent chaining, comparisons, or structured reports - Mention that results are live Metlink snapshots and require a Metlink Open Data API key
CLI
Set a free Metlink Open Data API key first:
export METLINK_API_KEY="..."
Run with:
python3 skills/nz-buses/scripts/cli.py <command> [flags]
Commands
routes [--query text] [--limit N] [--json]- list/search Metlink bus routesroute <route> [--limit N] [--json]- show one bus route and its stopsstops [--query text] [--near location-or-lat-lon] [--limit N] [--json]- search Metlink bus stopsstop <stop-id> [--limit N] [--json]- show stop details with live bus arrivalsarrivals <stop-id> [--limit N] [--json]- live bus arrivals for a Metlink stopvehicles [--route route] [--limit N] [--json]- live Metlink bus vehicle positionsalerts [--limit N] [--json]- active Metlink bus service alerts
Examples:
python3 skills/nz-buses/scripts/cli.py routes --limit 10
python3 skills/nz-buses/scripts/cli.py route 1 --limit 12
python3 skills/nz-buses/scripts/cli.py stops --near Lambton --limit 5
python3 skills/nz-buses/scripts/cli.py stop 5011 --limit 5
python3 skills/nz-buses/scripts/cli.py arrivals 5011 --json
python3 skills/nz-buses/scripts/cli.py vehicles --route 83 --limit 10 --json
python3 skills/nz-buses/scripts/cli.py alerts --json
Resources
- CLI entrypoint:
scripts/cli.py - API and stability notes:
references/api-notes.md
Notes
- Read-only only: no journey planning, booking, ticketing, account, or mutation actions
- Python stdlib only; no package install or browser automation is required for normal use
- Metlink requests use
METLINK_API_KEYand fail with a clear message when it is missing - Do not hardcode or commit Metlink API keys; use the
METLINK_API_KEYenvironment variable only - Bus filtering includes standard GTFS bus
route_type=3and Metlink school busroute_type=712; rail2, ferry4, and cable car5are excluded - The Metlink API returns live snapshots; stops, trips, delays, alerts, and vehicles can change quickly
- Canterbury Metro, ORC Bus, BayBus, and other non-Auckland bus networks are follow-ups, not v1 commands