at-transport

Query live Auckland Transport (AT) public transport data — stops, departures, service alerts, vehicle positions, routes, and network status. Use when the task involves Auckland buses, trains, ferries,

SKILL.md

GitHub

Auckland Transport

Goal

Query live Auckland public transport data from the AT API through a CLI that is easy for agents to script and easy for humans to scan. Covers real-time departures, service alerts, stop search, nearby stops, vehicle tracking, and network status.

Use this when

  • A user asks about Auckland public transport — buses, trains, ferries
  • A user wants real-time departure information from a specific stop
  • A user asks about service disruptions or alerts in Auckland
  • A user wants to find nearby stops or search for a stop by name
  • A user asks about live vehicle positions on the Auckland network
  • A user wants a quick overview of Auckland Transport network status

Do not use this for

  • Transport outside Auckland / New Zealand
  • Route planning or journey directions (use AT's journey planner)
  • Historical schedule data or timetable lookups
  • Fares or ticketing information
  • Traffic or road conditions

Preferred workflow

  1. Run scripts/cli.py with the narrowest subcommand that answers the task
  2. Use default human output for direct answers
  3. Use --json when another tool or agent needs machine-readable output

CLI

Run with:

python3 skills/at-transport/scripts/cli.py <command> [flags]

alerts [--limit N] [--json]

Active service alerts and disruptions across the Auckland network.

JSON shape:

  • timestamp
  • total_active
  • returned
  • alerts[] with id, severity_level, cause, effect, header_text, description_text, active_period, informed_entity

Examples:

python3 skills/at-transport/scripts/cli.py alerts
python3 skills/at-transport/scripts/cli.py alerts --limit 5
python3 skills/at-transport/scripts/cli.py alerts --json

departures <stop_id> [--limit N] [--json]

Real-time departures from a stop. Uses stop code (e.g. 11814) or full stop ID. Shows route, expected time, and delay. For parent stations, includes all child platform stops.

JSON shape:

  • stop with stop details
  • total_departures
  • returned
  • departures[] with route_id, route_short_name, route_type, trip_id, stop_id, stop_name, direction_id, scheduled_time, expected_time, delay_seconds, vehicle_id, vehicle_label

Key stop codes:

  • 11814 — Britomart (bus terminal)
  • 11815 — Customs St/Britomart
  • 11895 — Britomart Queens Arcade
  • 31986 — Britomart Lower Albert

Examples:

python3 skills/at-transport/scripts/cli.py departures 11814
python3 skills/at-transport/scripts/cli.py departures 7155 --limit 5
python3 skills/at-transport/scripts/cli.py departures 11814 --json

stops <query> [--limit N] [--json]

Search stops by name, code, or ID. Returns matching stops with location and type info.

JSON shape:

  • query
  • total_matches
  • returned
  • stops[] with stop_id, stop_code, stop_name, stop_lat, stop_lon, location_type, parent_station, platform_code

Examples:

python3 skills/at-transport/scripts/cli.py stops Britomart
python3 skills/at-transport/scripts/cli.py stops Newmarket
python3 skills/at-transport/scripts/cli.py stops 7155 --json

nearby <lat,lon> [--radius N] [--limit N] [--json]

Find stops near a geographic location. Radius in meters, defaults to 500m.

JSON shape:

  • location with lat, lon
  • radius_m
  • total_nearby
  • returned
  • stops[] with stop details plus distance_m

Examples:

python3 skills/at-transport/scripts/cli.py nearby --location=-36.844,174.768
python3 skills/at-transport/scripts/cli.py nearby --location=-36.844,174.768 --radius 1000
python3 skills/at-transport/scripts/cli.py nearby --location=-36.844,174.768 --json

route <route_id> [--json]

Show details for a specific route. Use full route ID (e.g. STH-201).

JSON shape:

  • route_id, route_short_name, route_long_name, route_type, agency_id, route_color

Examples:

python3 skills/at-transport/scripts/cli.py route STH-201
python3 skills/at-transport/scripts/cli.py route 70-221 --json

vehicles [--route <route_id>] [--limit N] [--json]

Live vehicle positions across the network, optionally filtered by route.

JSON shape:

  • timestamp
  • filter_route
  • total_vehicles
  • returned
  • vehicles[] with vehicle_id, label, lat, lon, speed, bearing, route_id, trip_id, last_update

Examples:

python3 skills/at-transport/scripts/cli.py vehicles
python3 skills/at-transport/scripts/cli.py vehicles --route STH-201
python3 skills/at-transport/scripts/cli.py vehicles --limit 10 --json

status [--json]

Overall network status summary — active trips, vehicles, on-time %, delays, and alert counts.

JSON shape:

  • timestamp
  • alerts_count
  • alerts_by_severity
  • active_trips
  • active_vehicles
  • delayed_trips
  • avg_delay_seconds
  • on_time_percentage

Examples:

python3 skills/at-transport/scripts/cli.py status
python3 skills/at-transport/scripts/cli.py status --json

Resources

  • CLI entrypoint: scripts/cli.py
  • Live smoke test: scripts/smoke_test.py

Notes

  • Set the user-supplied Auckland Transport subscription key in AT_API_KEY; the skill does not bundle credentials
  • Uses GTFS v3 for static data (stops, routes) and GTFS-RT legacy feed for real-time data (alerts, trip updates, vehicle positions)
  • Departures show only trips with active real-time tracking — vehicles currently approaching or at the stop
  • Parent stations (location_type=1) automatically include departures from child platform stops
  • Default output is human-readable; --json is intended for chaining into other tools or agent steps
  • Route types: 0=Tram, 2=Train, 3=Bus, 4=Ferry

Source notes

Read references/source-notes.md for source ownership, access, and freshness boundaries.