gtfs-nz
Read NZ public transport GTFS static timetables: feeds, stops, routes, trips, scheduled departures and route geometry. Use for Auckland Transport, Metlink (Wellington), BUSIT (Waikato) and Orbus (Otag
SKILL.mdskills/gtfs-nz/SKILL.md
GitHubNZ GTFS static timetables
Use scripts/cli.py for keyless NZ timetable baselines: registered feeds, stops,
routes, trips, scheduled departures and route shapes. Python stdlib only.
AT realtime departures, vehicles and alerts belong to at-transport, which
requires the user-supplied AT_API_KEY. This skill does not query realtime APIs.
Workflow
- Run
feeds --jsonto check the registry and feed validity dates; add--refreshfor a live download. - Select
--feed at,metlink,busitororbus. - Look up stops/routes first; use their exact GTFS IDs for departures/trips/shapes.
- Check
meta.warnings,meta.latest_data,meta.truncatedand the service date before using results. Static departures are schedules, not predictions or proof of operation.
Commands
Run python3 skills/gtfs-nz/scripts/cli.py <command> [flags].
Every command supports --json, --cache-dir PATH, and --max-age SECONDS
(default 86400). Every command supports --refresh; data queries support --limit N (default 100,
maximum 10000). All commands reuse fresh ZIPs unless --refresh is given. Expired caches are refreshed; a failed refresh is an error.
feeds [--feed at|metlink|busit|orbus]: verified registry, cached or live download status, ZIP size, table names and originalfeed_inforecords. Per-feed failures have a status and error; partial failures also addmeta.warnings. A total outage fails with a non-zero exit code. Each available record reportscached.stops --feed at [--bbox minLon,minLat,maxLon,maxLat] [--near lon,lat --radius METRES] [--format json|geojson]: WGS84 stop locations; radius defaults to 500 m. Nearby results sort by distance. Both spatial filters may be combined. Non-spatial JSON can retain stops without coordinates; spatial output excludes those stops.routes --feed at [--type bus|rail|ferry|tram|cable|other]: original route columns plusmode. Standard and extended GTFS types map to these modes (including school buses); unrecognised types map toother. See source notes for the mapping.trips --feed at --route ROUTE: timetable trips, including service and shape IDs. Lists all published trips, not only trips operating today.departures --feed at --stop STOP [--date YYYY-MM-DD] [--time HH:MM[:SS]]: departures fromstop_timesjoined to trips,calendarandcalendar_dates. Date defaults to today in Pacific/Auckland; time defaults to00:00and is an inclusive minimum. Results sort by scheduled time. Parent stations include their child platforms. Use exact stop IDs or unambiguous stop codes.shapes --feed at --route ROUTE --format geojson [--bbox minLon,minLat,maxLon,maxLat]: one LineString per published shape, sorted by numeric point sequence. A bbox selects intersecting shapes and returns their complete geometry; it does not clip.
Routes accept exact route_id or an unambiguous route_short_name.
IDs can change between feed versions. Negative coordinate strings are easiest
with --bbox=... or --near=....
python3 skills/gtfs-nz/scripts/cli.py feeds --json
python3 skills/gtfs-nz/scripts/cli.py stops --feed at --near 174.768,-36.844 --radius 500 --format geojson --json
python3 skills/gtfs-nz/scripts/cli.py stops --feed metlink --bbox=174.75,-41.30,174.80,-41.25 --json
python3 skills/gtfs-nz/scripts/cli.py routes --feed at --type rail --json
python3 skills/gtfs-nz/scripts/cli.py trips --feed at --route 101-202 --json
python3 skills/gtfs-nz/scripts/cli.py departures --feed at --stop 11814 --date 2026-10-16 --time 08:00 --json
python3 skills/gtfs-nz/scripts/cli.py shapes --feed at --route 101-202 --format geojson --json
Interpretation and output
--date is a GTFS service date, not a civil-day window. 25:10:00 means
01:10 after that service date and stays attached to that service's calendar.
For early-morning civil-day analysis, query the previous service date with
--time 24:00 as well as the current one. No UTC timestamps are fabricated across
NZ daylight saving transitions.
JSON successes use {"meta": {...}, "results": [...]}. Spatial GeoJSON uses
type, features and the same meta foreign member; --format geojson implies
machine-readable output, including errors. Provenance lives under meta:
source_url, publisher and ISO UTC retrieved_at, plus licence when known.
For the mixed-source feeds command, records also carry each source's provenance.
meta.latest_data is the stated validity range as an ISO date string (start/end);
meta.feed_info retains source dates and version. These are validity dates, not
publication timestamps. BUSIT has no feed_info.txt, so latest_data is omitted
with a warning and its unknown licence is omitted. Cache hits retain the original
retrieval time. meta.total counts all matches; meta.returned and
meta.truncated describe the output limit. Original GTFS identifiers and most
columns remain strings; spatial stop coordinates become numbers.
Departures exclude stops with pickup_type=1. Terminal rows remain visible with
terminates: true; these are terminal arrivals, so filter them out for boarding
analysis. Untimed stop_times are counted and warned about rather than interpolated.
Conditional pickup fields remain visible. Frequency-based trips serving the selected
stop on the service date are unsupported (exit 7); unrelated frequency trips add a
warning. No journey planning, realtime conditions or frequency expansion is provided.
Resources
- Read references/source-notes.md for verified endpoints, licences, cache/memory limits and fixture provenance.
scripts/test_contract.py: deterministic CLI and GTFS edge-case checks usingtests/fixtures/at-sample.zip, trimmed from the real AT feed.scripts/smoke_test.py: bounded fixture and live feed/query checks.
Default cache: $XDG_CACHE_HOME/thecolab-gtfs-nz (or ~/.cache/thecolab-gtfs-nz).
Set GTFS_NZ_CACHE_DIR or --cache-dir to override it. Downloads have a 10 s
socket timeout and a 50 s download deadline, a 128 MiB compressed cap and 1 GiB expanded-size cap; tables are
streamed from the ZIP without extracting files. Errors have actionable messages
and repository exit codes (2 input, 4 access, 5 network, 6 parser/cache, 7 unsupported).