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.md

GitHub

NZ 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

  1. Run feeds --json to check the registry and feed validity dates; add --refresh for a live download.
  2. Select --feed at, metlink, busit or orbus.
  3. Look up stops/routes first; use their exact GTFS IDs for departures/trips/shapes.
  4. Check meta.warnings, meta.latest_data, meta.truncated and 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 original feed_info records. Per-feed failures have a status and error; partial failures also add meta.warnings. A total outage fails with a non-zero exit code. Each available record reports cached.
  • 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 plus mode. Standard and extended GTFS types map to these modes (including school buses); unrecognised types map to other. 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 from stop_times joined to trips, calendar and calendar_dates. Date defaults to today in Pacific/Auckland; time defaults to 00:00 and 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 using tests/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).