Auckland Transport Integration

Mai's Commute Assistant 🌸

Overview

This project integrates with Auckland Transport APIs to provide:

• Realtime departures for each leg of a configured commute
• Per-leg ETA calculation using scheduled arrival times and live delay data
• Service alerts filtered to the stops and routes of the day's commute
• Sequential leg planning — each leg's earliest board time is derived from the previous arrival

Goal

Primary goal is to help Mai (OpenClaw agent) access transport information and deliver relevant commute updates.

Project Structure

transit-api/
├── api_definitions/          # AT API specifications (YAML)
├── data/                     # Static GTFS data for reference (CSV)
├── integrations/             # Python integration scripts
│   ├── __init__.py
│   ├── at_client.py          # Low-level AT API wrapper (static + realtime)
│   ├── at_processor.py       # High-level processing layer (dataclasses, filtering)
│   ├── commute_plan.json     # Your commute configuration (stops, routes, times)
│   ├── commute_tracker.py    # JSON-driven commute planner (main entry point)
│   ├── find_stops.py         # Interactive stop/trip/route lookup helper
│   ├── alert_monitor.py      # Continuous alert monitoring service
│   ├── validate_commute.py   # One-off config validation
│   ├── requirements.txt
│   └── cache/                # Cached static API responses (24h TTL)
└── secrets/                  # API keys (gitignored)

Setup

1. API Key: Place your Auckland Transport API key in secrets/api-key.txt

2. Install Dependencies:

cd integrations
pip install -r requirements.txt

3. Configure Your Commute: Edit integrations/commute_plan.json with your stops, routes, and departure times. Use the stop finder to look up correct IDs:

python integrations/find_stops.py "Glen Eden"

4. Check Your Commute:

# Auto-select the next upcoming commute
python integrations/commute_tracker.py

# Or select manually
python integrations/commute_tracker.py --commute morning
python integrations/commute_tracker.py --commute evening

Commute Plan Configuration

All commute configuration lives in integrations/commute_plan.json. Each commute has a departure_time and a list of legs. Example leg:

{
  "route_id": "17-203",
  "route_short_name": "17",
  "direction_id": 0,
  "embark_stop_id": "5429-821b0f7e",
  "embark_stop_name": "Glen Eden Station",
  "disembark_stop_id": "5000-e8cc2e62",
  "disembark_stop_name": "Terra Nova Street",
  "walk_minutes": 1
}

Use find_stops.py to identify correct stop IDs and verify direction by drilling down: search by name → select stop → select trip → view all stops on that trip.

How the Tracker Works

1. Loads commute_plan.json and selects the commute to run
2. For each leg:
   • Computes earliest board time = previous ETA + walk_minutes
   • Fetches upcoming services at the embark stop for the route via /stops/{id}/stoptrips
   • Selects the first service that reaches the configured disembark stop
   • Fetches realtime delay via trip updates
   • Computes ETA = scheduled arrival at disembark stop + delay
3. Collects service alerts filtered to configured stops and routes, active today only
4. Prints a leg-by-leg summary and a plain-English outline

API Documentation

• Static GTFS: https://api.at.govt.nz/gtfs/v3
• Realtime: https://api.at.govt.nz/realtime/legacy

License

Private - for personal use only.