name: cta description: Chicago CTA transit — real-time L train arrivals, bus predictions, service alerts, and route info. Use when the user asks about Chicago public transit, L train schedules, CTA bus times, service alerts, or nearby stops. homepage: "https://github.com/brianleach/cta-skill" license: MIT metadata: clawhub: emoji: "🚇" tags: [transit, chicago, cta, transportation, bus, train, l-train, schedule] requires: bins: ["node", "unzip"] env: ["CTA_TRAIN_API_KEY", "CTA_BUS_API_KEY"] files: ["scripts/cta.mjs"] install: - id: npm-deps kind: shell command: "npm install --prefix $SKILL_DIR" label: "Install Node.js dependencies"

CTA Chicago Transit

Real-time Chicago CTA transit data — L train arrivals, bus predictions, service alerts, and route information. Requires free API keys for train and bus data; alerts work without any keys.

When to Use

• User asks about CTA, L train, Blue Line, Red Line, Brown Line, or any Chicago rail line
• User asks about Chicago bus routes, bus tracker, or train tracker
• User asks "when is the next train" or "is the Red Line running" in a Chicago context
• User mentions specific CTA stations (O'Hare, Midway, Clark/Lake, Belmont, etc.)
• User asks about CTA fares, Ventra, or how to ride Chicago transit
• User asks about CTA service alerts, delays, or detours
• User asks about nearby stops or route information in Chicago

Data Sources

CTA uses 3 proprietary REST APIs. Train Tracker and Bus Tracker require free API keys. Customer Alerts is open access.

Train Tracker API (requires CTA_TRAIN_API_KEY)

Get a free key at: https://www.transitchicago.com/developers/traintrackerapply/

| Endpoint | Description | |----------|-------------| | Arrivals by station (mapid) | Train arrivals at a parent station | | Arrivals by stop (stpid) | Train arrivals at a directional stop | | Train positions (rt) | Live positions of all trains on a line | | Follow a run (runnumber) | Track a specific train run |

Data refreshes approximately once per minute. Daily limit: 50,000 requests per key.

Bus Tracker API v2 (requires CTA_BUS_API_KEY)

Get a free key at: https://www.transitchicago.com/developers/bustracker/

| Endpoint | Description | |----------|-------------| | Predictions by stop | Bus arrival predictions at a stop | | Predictions by vehicle | Predictions for a specific bus | | Vehicle locations | Live bus positions on a route | | Routes list | All active bus routes | | Route directions | Available directions for a route | | Stops for route/direction | All stops along a route |

Bus data updates approximately every 30 seconds.

Customer Alerts API (NO key required)

| Endpoint | Description | |----------|-------------| | Route statuses | Current status of all routes | | All alerts | All active service alerts | | Alerts by route | Alerts filtered by route | | Alerts by station | Alerts filtered by station |

GTFS Static Feed

| Feed | Format | URL | |------|--------|-----| | GTFS Static (zip) | ZIP | https://www.transitchicago.com/downloads/sch_data/google_transit.zip |

Used for stop names, route info, and schedule lookups. Same stop IDs used across all APIs.

Implementation

Quick Start: Use the helper scripts

The scripts in this skill's scripts/ directory handle fetching, parsing, and presenting CTA data.

Script: scripts/cta.mjs

Main entry point. Supports these commands:

# L train arrivals
node scripts/cta.mjs arrivals --station "Clark/Lake"
node scripts/cta.mjs arrivals --mapid 40380
node scripts/cta.mjs arrivals --stop 30070
node scripts/cta.mjs arrivals --stop-search "ohare"
node scripts/cta.mjs arrivals --stop-search "belmont" --route Red

# Bus predictions
node scripts/cta.mjs bus-arrivals --stop 456
node scripts/cta.mjs bus-arrivals --stop 456 --route 22
node scripts/cta.mjs bus-arrivals --stop-search "michigan"

# Vehicle tracking
node scripts/cta.mjs vehicles --route Red
node scripts/cta.mjs bus-vehicles --route 22

# Service alerts
node scripts/cta.mjs alerts
node scripts/cta.mjs alerts --route Red

# Routes and stops
node scripts/cta.mjs routes
node scripts/cta.mjs bus-routes
node scripts/cta.mjs stops --search "belmont"
node scripts/cta.mjs stops --near 41.8781,-87.6298 --radius 0.3
node scripts/cta.mjs route-info --route Red
node scripts/cta.mjs route-info --route 22

# Maintenance
node scripts/cta.mjs refresh-gtfs

Setup: API Keys

Train and bus commands require free API keys:

1. Train Tracker key: Apply at https://www.transitchicago.com/developers/traintrackerapply/
2. Bus Tracker key: Apply at https://www.transitchicago.com/developers/bustracker/
3. Set environment variables: CTA_TRAIN_API_KEY and CTA_BUS_API_KEY

Alert commands work without any keys.

Setup: GTFS Static Data

On first use, run node scripts/cta.mjs refresh-gtfs to download and extract the static GTFS data (routes, stops, schedules) to ~/.cta/gtfs/. This only needs to be refreshed when CTA updates their schedule.

L Train Lines Reference

| Route Code | Line | Terminals | |-----------|------|-----------| | Red | Red Line | Howard ↔ 95th/Dan Ryan | | Blue | Blue Line | O'Hare ↔ Forest Park | | Brn | Brown Line | Kimball ↔ Loop | | G | Green Line | Harlem/Lake ↔ Ashland/63rd or Cottage Grove | | Org | Orange Line | Midway ↔ Loop | | P | Purple Line | Linden ↔ Howard (Express to Loop weekdays) | | Pink | Pink Line | 54th/Cermak ↔ Loop | | Y | Yellow Line | Dempster-Skokie ↔ Howard |

Key Bus Routes Reference

| Route | Name | Notes | |-------|------|-------| | 22 | Clark | Major north-south corridor | | 36 | Broadway | North Side lakefront | | 77 | Belmont | Major east-west crosstown | | 151 | Sheridan | Lakefront express | | 146 | Inner Drive/Michigan Express | Loop to north lakefront | | 8 | Halsted | Long north-south route | | 9 | Ashland | Major north-south corridor | | 49 | Western | Longest route in system | | 66 | Chicago | Major east-west route | | 79 | 79th | Major south side east-west |

CTA Fares Reference (2026)

| Fare Type | Price | |-----------|-------| | Regular (Ventra/contactless) | $2.50 | | Bus transfer | $0.25 | | Rail-to-rail transfer | Free within 2 hours | | Reduced fare | $1.25 | | 1-Day Pass | $5.00 | | 3-Day Pass | $15.00 | | 7-Day Pass | $20.00 | | 30-Day Pass | $75.00 |

Payment via Ventra card, Ventra app, or contactless bank card. Transfers valid for 2 hours.

Tips for Users

• Station IDs are in the 4xxxx range (parent stations); stop IDs in the 3xxxx range (directional)
• Use --station or --stop-search for name-based lookups; use --mapid for exact station IDs
• Alerts always work — no API key needed — so check alerts first if something seems wrong
• Train data refreshes ~1 minute; bus data refreshes ~30 seconds
• For the Loop, trains may show as arriving from different directions depending on the line

Error Handling

• If CTA_TRAIN_API_KEY is not set, train commands print a helpful message with the signup URL
• If CTA_BUS_API_KEY is not set, bus commands print a helpful message with the signup URL
• Alert commands always work (no key required)
• Invalid station/stop searches show "No matching station found" with suggestions
• Network errors and API error responses produce friendly messages

Response Formatting

When presenting transit info to the user:

• Lead with the most actionable info (next arrival time, active alerts)
• Show times in 12-hour format with AM/PM
• Include line color AND destination (e.g., "Red Line toward 95th/Dan Ryan")
• For trains: show "Due" for imminent arrivals, minutes for upcoming
• For bus predictions, show estimated minutes until arrival
• If there are active service alerts for the route being queried, always mention them

External Endpoints

| Endpoint | Data Sent | Data Received | |----------|-----------|---------------| | https://lapi.transitchicago.com/api/1.0/ttarrivals.aspx | API key (query param, HTTPS) | Train arrivals (JSON) | | https://lapi.transitchicago.com/api/1.0/ttpositions.aspx | API key (query param, HTTPS) | Train positions (JSON) | | https://lapi.transitchicago.com/api/1.0/ttfollow.aspx | API key (query param, HTTPS) | Train run details (JSON) | | https://www.ctabustracker.com/bustime/api/v2/* | API key (query param, HTTPS) | Bus predictions/positions (JSON) | | https://www.transitchicago.com/api/1.0/routes.aspx | None (GET only) | Route statuses (JSON) | | https://www.transitchicago.com/api/1.0/alerts.aspx | None (GET only) | Service alerts (JSON) | | https://www.transitchicago.com/downloads/sch_data/google_transit.zip | None (GET only) | GTFS static data (ZIP) |

All API calls use HTTPS. API keys are passed as query parameters to CTA's official APIs. No other user data is transmitted.

Security & Privacy

• API keys required — Train and Bus Tracker APIs require free developer keys passed as URL query parameters
• No user data transmitted — requests contain only API keys and route/stop identifiers, no personal information
• Local storage only — GTFS static data is cached locally at ~/.cta/gtfs/; no data is written elsewhere
• No telemetry — this skill does not phone home or collect usage data
• Input handling — stop names and route IDs from user input are used only for local filtering, never interpolated into shell commands

Trust Statement

This skill reads publicly available transit data from CTA's official APIs. API keys are used only for CTA API authentication. The skill does not access, store, or transmit any personal information beyond the API keys configured by the user.