Chicago Metra Commuter Rail
Real-time Chicago Metra commuter rail data — train arrivals (GTFS-RT protobuf), vehicle positions, service alerts, schedule info, and fare calculation for all 11 Metra lines serving the six-county northeastern Illinois region. Requires a free API key for all feeds.
When to Use
- User asks about Metra, Chicago commuter rail, or commuter trains in Chicago
- User asks "when is the next train" in a Chicago suburban context
- User mentions specific Metra lines: BNSF, UP-N, UP-NW, UP-W, MD-N, MD-W, ME (Metra Electric), RI (Rock Island), NCS, HC (Heritage Corridor), SWS (SouthWest Service)
- User mentions specific Metra stations: Union Station, Ogilvie, Millennium Station, LaSalle Street, Naperville, Aurora, Downers Grove, Evanston, Highland Park, etc.
- User asks about Metra service alerts, delays, or construction
- User asks about Metra fares, zones, monthly passes, Ventra
- User asks about Chicago train schedules (distinguish from CTA "L" trains — Metra is commuter rail)
When NOT to Use
- User asks about CTA trains (the "L"), CTA buses, or Pace buses — those are separate systems
- User asks about Amtrak long-distance trains at Union Station
Data Sources
Metra uses standard GTFS-RT protobuf feeds served from a single base URL with Bearer token authentication. No proprietary extensions — clean standard GTFS-RT.
GTFS Realtime Feeds (Protobuf, requires METRA_API_KEY)
Get a free key at: https://metra.com/developers
| Feed |
Endpoint |
Description |
| Trip Updates |
GET /gtfs/public/tripupdates |
Real-time arrival/departure predictions |
| Vehicle Positions |
GET /gtfs/public/positions |
GPS locations of active trains |
| Alerts |
GET /gtfs/public/alerts |
Service alerts, delays, construction notices |
Base URL: https://gtfspublic.metrarr.com
Authentication: Authorization: Bearer {METRA_API_KEY} header.
Data updates every 30 seconds. No need to poll more frequently.
GTFS Static Feed
| Feed |
URL |
| GTFS Static (zip) |
https://schedules.metrarail.com/gtfs/schedule.zip |
| Published timestamp |
https://schedules.metrarail.com/gtfs/published.txt |
Static schedule updates regularly (sometimes within 24 hours). New scheduled updates publish at 3:00 AM.
Important Notes from Metra
- If realtime data is unavailable for a trip, assume the static schedule is correct
- Vehicle positions may drop when trains are underground or at terminals (GPS loss)
- Trip updates may be provided hours in advance for annulled or added trains
- If an alert is in the feed, it's active; if it's not, it's no longer active (regardless of active_period)
Implementation
Script: scripts/metra.mjs
Main entry point. Supports these commands:
# Train arrivals
node scripts/metra.mjs arrivals --station "Union Station"
node scripts/metra.mjs arrivals --station "Naperville" --line BNSF
node scripts/metra.mjs arrivals --station "Ogilvie"
node scripts/metra.mjs arrivals --station "Millennium Station" --line ME
# Vehicle tracking
node scripts/metra.mjs vehicles --line BNSF
node scripts/metra.mjs vehicles --line UP-N
node scripts/metra.mjs vehicles --line ME
# Service alerts
node scripts/metra.mjs alerts
node scripts/metra.mjs alerts --line BNSF
node scripts/metra.mjs alerts --line RI
# Routes and stops
node scripts/metra.mjs routes
node scripts/metra.mjs stops --search "downers grove"
node scripts/metra.mjs stops --line BNSF
node scripts/metra.mjs stops --near 41.8781,-87.6298
node scripts/metra.mjs route-info --line UP-NW
# Fares
node scripts/metra.mjs fares
node scripts/metra.mjs fares --from "Union Station" --to "Naperville"
# Schedule
node scripts/metra.mjs schedule --station "Naperville"
node scripts/metra.mjs schedule --station "Ogilvie" --line UP-N
# Maintenance
node scripts/metra.mjs refresh-gtfs
Setup: API Key
All Metra feeds require authentication:
- Register for a free key at https://metra.com/developers
- Set environment variable:
METRA_API_KEY
Setup: GTFS Static Data
On first use, run node scripts/metra.mjs refresh-gtfs to download and extract the static GTFS data (routes, stops, schedules) to ~/.metra/gtfs/. Refresh periodically or when Metra updates their schedule.
Metra Lines Reference
| Line Code |
Line Name |
Color |
Downtown Terminal |
Outer Terminal |
| BNSF |
BNSF Railway |
Orange |
Union Station (CUS) |
Aurora |
| ME |
Metra Electric |
Teal |
Millennium Station |
University Park / South Chicago / Blue Island |
| HC |
Heritage Corridor |
Purple |
Union Station (CUS) |
Joliet |
| MD-N |
Milwaukee District North |
Light Green |
Union Station (CUS) |
Fox Lake |
| MD-W |
Milwaukee District West |
Light Green |
Union Station (CUS) |
Elburn / Big Timber |
| NCS |
North Central Service |
Gold |
Union Station (CUS) |
Antioch |
| RI |
Rock Island |
Red |
LaSalle Street Station |
Joliet |
| SWS |
SouthWest Service |
Dark Purple |
Union Station (CUS) |
Manhattan |
| UP-N |
Union Pacific North |
Dark Green |
Ogilvie Transportation Center (OTC) |
Kenosha |
| UP-NW |
Union Pacific Northwest |
Blue |
Ogilvie Transportation Center (OTC) |
Harvard / McHenry |
| UP-W |
Union Pacific West |
Blue |
Ogilvie Transportation Center (OTC) |
Elburn |
Downtown Terminal Stations
- Chicago Union Station (CUS) — Zone 1 — BNSF, HC, MD-N, MD-W, NCS, SWS
- Ogilvie Transportation Center (OTC) — Zone 1 — UP-N, UP-NW, UP-W
- LaSalle Street Station — Zone 1 — RI
- Millennium Station — Zone 1 — ME
Metra Fares Reference (4-Zone System, effective Feb 2024)
| Ticket Type |
Zones 1-2 |
Zones 1-2-3 |
Zones 1-2-3-4 |
Zones 2-3-4 (no downtown) |
| One-Way |
$3.75 |
$5.50 |
$6.75 |
$3.75 |
| Day Pass |
$7.50 |
$11.00 |
$13.50 |
$7.50 |
| Day Pass 5-Pack |
$35.75 |
$52.25 |
$64.25 |
$35.75 |
| Monthly Pass |
$75.00 |
$110.00 |
$135.00 |
$75.00 |
Special Passes:
- Saturday/Sunday/Holiday Day Pass: $7.00 (systemwide)
- Weekend Pass (Ventra app only): $10.00 (systemwide)
- Regional Connect Pass (with Monthly): $30.00 (adds CTA + Pace)
- Onboard Surcharge (cash on train): $5.00
Monthly Passes are valid for unlimited rides on weekdays between selected zones and systemwide on weekends.
Tips for Users
- Metra uses inbound (toward downtown Chicago) and outbound (away from downtown) for directions
- Train numbers matter — Metra riders often know their train by number (e.g., "the 7:42 BNSF" or "Train 1252")
- Different lines use different downtown terminals — always note which terminal
- Peak trains run during rush hours; off-peak and weekend service is less frequent
- If real-time data is unavailable, the schedule command shows static times
- Use
--line to filter by specific Metra line code (BNSF, UP-N, etc.)
Error Handling
- If
METRA_API_KEY is not set, all commands print a helpful message with the signup URL
- Invalid station names show "No matching station found" with a suggestion to use stops --search
- No real-time data available → fall back to static schedule with a note
- Network errors produce friendly messages
- GPS dropout for vehicle positions → note that train may be underground or at terminal
Response Formatting
When presenting transit info to the user:
- Lead with the most actionable info (next arrival time, active alerts)
- Show line name AND train number (e.g., "BNSF Train 1252 inbound")
- Show times in 12-hour format with AM/PM
- For arrivals: show both real-time ETA and scheduled time when available
- Always note the downtown terminal for the line
- If there are active service alerts for the line being queried, mention them
External Endpoints
| Endpoint |
Data Sent |
Data Received |
gtfspublic.metrarr.com/gtfs/public/tripupdates |
API key (Bearer header, HTTPS) |
Trip updates (Protobuf) |
gtfspublic.metrarr.com/gtfs/public/positions |
API key (Bearer header, HTTPS) |
Vehicle positions (Protobuf) |
gtfspublic.metrarr.com/gtfs/public/alerts |
API key (Bearer header, HTTPS) |
Service alerts (Protobuf) |
schedules.metrarail.com/gtfs/schedule.zip |
None (GET only) |
GTFS static data (ZIP) |
schedules.metrarail.com/gtfs/published.txt |
None (GET only) |
Schedule publish timestamp (text) |
All API calls use HTTPS. The API key is passed as a Bearer token in the Authorization header. No other user data is transmitted.
Security & Privacy
- API key required — All GTFS-RT feeds require a free developer key passed as a Bearer token in the Authorization header
- No user data transmitted — Requests contain only the API key; no personal information
- Local storage only — GTFS static data is cached locally at
~/.metra/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 Metra's official GTFS-RT feeds. The API key is used only for Metra API authentication. The skill does not access, store, or transmit any personal information beyond the API key configured by the user.
1---2name: metra3description: Chicago Metra commuter rail — real-time train arrivals, vehicle tracking, service alerts, and schedule info for all 11 Metra lines serving the Chicago metropolitan area. Use when the user asks about Metra trains, Chicago commuter rail, or specific Metra lines and stations.4license: MIT5---6
7# Chicago Metra Commuter Rail
8
9Real-time Chicago Metra commuter rail data — train arrivals (GTFS-RT protobuf), vehicle positions, service alerts, schedule info, and fare calculation for all 11 Metra lines serving the six-county northeastern Illinois region. Requires a free API key for all feeds.
10
11## When to Use
12
13- User asks about Metra, Chicago commuter rail, or commuter trains in Chicago
14- User asks "when is the next train" in a Chicago suburban context
15- User mentions specific Metra lines: BNSF, UP-N, UP-NW, UP-W, MD-N, MD-W, ME (Metra Electric), RI (Rock Island), NCS, HC (Heritage Corridor), SWS (SouthWest Service)
16- User mentions specific Metra stations: Union Station, Ogilvie, Millennium Station, LaSalle Street, Naperville, Aurora, Downers Grove, Evanston, Highland Park, etc.
17- User asks about Metra service alerts, delays, or construction
18- User asks about Metra fares, zones, monthly passes, Ventra
19- User asks about Chicago train schedules (distinguish from CTA "L" trains — Metra is commuter rail)
20
21### When NOT to Use
22
23- User asks about CTA trains (the "L"), CTA buses, or Pace buses — those are separate systems
24- User asks about Amtrak long-distance trains at Union Station
25
26## Data Sources
27
28Metra uses standard GTFS-RT protobuf feeds served from a single base URL with Bearer token authentication. No proprietary extensions — clean standard GTFS-RT.
29
30### GTFS Realtime Feeds (Protobuf, requires `METRA_API_KEY`)
31
32Get a free key at: https://metra.com/developers
33
34| Feed | Endpoint | Description |
35|------|----------|-------------|
36| Trip Updates | `GET /gtfs/public/tripupdates` | Real-time arrival/departure predictions |
37| Vehicle Positions | `GET /gtfs/public/positions` | GPS locations of active trains |
38| Alerts | `GET /gtfs/public/alerts` | Service alerts, delays, construction notices |
39
40Base URL: `https://gtfspublic.metrarr.com`
41
42Authentication: `Authorization: Bearer {METRA_API_KEY}` header.
43
44Data updates every 30 seconds. No need to poll more frequently.
45
46### GTFS Static Feed
47
48| Feed | URL |
49|------|-----|
50| GTFS Static (zip) | `https://schedules.metrarail.com/gtfs/schedule.zip` |
51| Published timestamp | `https://schedules.metrarail.com/gtfs/published.txt` |
52
53Static schedule updates regularly (sometimes within 24 hours). New scheduled updates publish at 3:00 AM.
54
55### Important Notes from Metra
56
57- If realtime data is unavailable for a trip, assume the static schedule is correct
58- Vehicle positions may drop when trains are underground or at terminals (GPS loss)
59- Trip updates may be provided hours in advance for annulled or added trains
60- If an alert is in the feed, it's active; if it's not, it's no longer active (regardless of active_period)
61
62## Implementation
63
64### Script: `scripts/metra.mjs`
65
66Main entry point. Supports these commands:
67
68```bash
69# Train arrivals
70node scripts/metra.mjs arrivals --station "Union Station"
71node scripts/metra.mjs arrivals --station "Naperville" --line BNSF
72node scripts/metra.mjs arrivals --station "Ogilvie"
73node scripts/metra.mjs arrivals --station "Millennium Station" --line ME
74
75# Vehicle tracking
76node scripts/metra.mjs vehicles --line BNSF
77node scripts/metra.mjs vehicles --line UP-N
78node scripts/metra.mjs vehicles --line ME
79
80# Service alerts
81node scripts/metra.mjs alerts
82node scripts/metra.mjs alerts --line BNSF
83node scripts/metra.mjs alerts --line RI
84
85# Routes and stops
86node scripts/metra.mjs routes
87node scripts/metra.mjs stops --search "downers grove"
88node scripts/metra.mjs stops --line BNSF
89node scripts/metra.mjs stops --near 41.8781,-87.6298
90node scripts/metra.mjs route-info --line UP-NW
91
92# Fares
93node scripts/metra.mjs fares
94node scripts/metra.mjs fares --from "Union Station" --to "Naperville"
95
96# Schedule
97node scripts/metra.mjs schedule --station "Naperville"
98node scripts/metra.mjs schedule --station "Ogilvie" --line UP-N
99
100# Maintenance
101node scripts/metra.mjs refresh-gtfs
102```
103
104### Setup: API Key
105
106All Metra feeds require authentication:
107
1081. Register for a free key at https://metra.com/developers
1092. Set environment variable: `METRA_API_KEY`
110
111### Setup: GTFS Static Data
112
113On first use, run `node scripts/metra.mjs refresh-gtfs` to download and extract the static GTFS data (routes, stops, schedules) to `~/.metra/gtfs/`. Refresh periodically or when Metra updates their schedule.
114
115### Metra Lines Reference
116
117| Line Code | Line Name | Color | Downtown Terminal | Outer Terminal |
118|-----------|-----------|-------|-------------------|----------------|
119| BNSF | BNSF Railway | Orange | Union Station (CUS) | Aurora |
120| ME | Metra Electric | Teal | Millennium Station | University Park / South Chicago / Blue Island |
121| HC | Heritage Corridor | Purple | Union Station (CUS) | Joliet |
122| MD-N | Milwaukee District North | Light Green | Union Station (CUS) | Fox Lake |
123| MD-W | Milwaukee District West | Light Green | Union Station (CUS) | Elburn / Big Timber |
124| NCS | North Central Service | Gold | Union Station (CUS) | Antioch |
125| RI | Rock Island | Red | LaSalle Street Station | Joliet |
126| SWS | SouthWest Service | Dark Purple | Union Station (CUS) | Manhattan |
127| UP-N | Union Pacific North | Dark Green | Ogilvie Transportation Center (OTC) | Kenosha |
128| UP-NW | Union Pacific Northwest | Blue | Ogilvie Transportation Center (OTC) | Harvard / McHenry |
129| UP-W | Union Pacific West | Blue | Ogilvie Transportation Center (OTC) | Elburn |
130
131### Downtown Terminal Stations
132
133- **Chicago Union Station (CUS)** — Zone 1 — BNSF, HC, MD-N, MD-W, NCS, SWS
134- **Ogilvie Transportation Center (OTC)** — Zone 1 — UP-N, UP-NW, UP-W
135- **LaSalle Street Station** — Zone 1 — RI
136- **Millennium Station** — Zone 1 — ME
137
138### Metra Fares Reference (4-Zone System, effective Feb 2024)
139
140| Ticket Type | Zones 1-2 | Zones 1-2-3 | Zones 1-2-3-4 | Zones 2-3-4 (no downtown) |
141|-------------|-----------|-------------|---------------|---------------------------|
142| One-Way | $3.75 | $5.50 | $6.75 | $3.75 |
143| Day Pass | $7.50 | $11.00 | $13.50 | $7.50 |
144| Day Pass 5-Pack | $35.75 | $52.25 | $64.25 | $35.75 |
145| Monthly Pass | $75.00 | $110.00 | $135.00 | $75.00 |
146
147Special Passes:
148- Saturday/Sunday/Holiday Day Pass: $7.00 (systemwide)
149- Weekend Pass (Ventra app only): $10.00 (systemwide)
150- Regional Connect Pass (with Monthly): $30.00 (adds CTA + Pace)
151- Onboard Surcharge (cash on train): $5.00
152
153Monthly Passes are valid for unlimited rides on weekdays between selected zones and systemwide on weekends.
154
155### Tips for Users
156
157- Metra uses **inbound** (toward downtown Chicago) and **outbound** (away from downtown) for directions
158- Train numbers matter — Metra riders often know their train by number (e.g., "the 7:42 BNSF" or "Train 1252")
159- Different lines use different downtown terminals — always note which terminal
160- Peak trains run during rush hours; off-peak and weekend service is less frequent
161- If real-time data is unavailable, the schedule command shows static times
162- Use `--line` to filter by specific Metra line code (BNSF, UP-N, etc.)
163
164### Error Handling
165
166- If `METRA_API_KEY` is not set, all commands print a helpful message with the signup URL
167- Invalid station names show "No matching station found" with a suggestion to use stops --search
168- No real-time data available → fall back to static schedule with a note
169- Network errors produce friendly messages
170- GPS dropout for vehicle positions → note that train may be underground or at terminal
171
172### Response Formatting
173
174When presenting transit info to the user:
175- Lead with the most actionable info (next arrival time, active alerts)
176- Show line name AND train number (e.g., "BNSF Train 1252 inbound")
177- Show times in 12-hour format with AM/PM
178- For arrivals: show both real-time ETA and scheduled time when available
179- Always note the downtown terminal for the line
180- If there are active service alerts for the line being queried, mention them
181
182## External Endpoints
183
184| Endpoint | Data Sent | Data Received |
185|----------|-----------|---------------|
186| `gtfspublic.metrarr.com/gtfs/public/tripupdates` | API key (Bearer header, HTTPS) | Trip updates (Protobuf) |
187| `gtfspublic.metrarr.com/gtfs/public/positions` | API key (Bearer header, HTTPS) | Vehicle positions (Protobuf) |
188| `gtfspublic.metrarr.com/gtfs/public/alerts` | API key (Bearer header, HTTPS) | Service alerts (Protobuf) |
189| `schedules.metrarail.com/gtfs/schedule.zip` | None (GET only) | GTFS static data (ZIP) |
190| `schedules.metrarail.com/gtfs/published.txt` | None (GET only) | Schedule publish timestamp (text) |
191
192All API calls use HTTPS. The API key is passed as a Bearer token in the Authorization header. No other user data is transmitted.
193
194## Security & Privacy
195
196- **API key required** — All GTFS-RT feeds require a free developer key passed as a Bearer token in the Authorization header
197- **No user data transmitted** — Requests contain only the API key; no personal information
198- **Local storage only** — GTFS static data is cached locally at `~/.metra/gtfs/`; no data is written elsewhere
199- **No telemetry** — This skill does not phone home or collect usage data
200- **Input handling** — Stop names and route IDs from user input are used only for local filtering, never interpolated into shell commands
201
202## Trust Statement
203
204This skill reads publicly available transit data from Metra's official GTFS-RT feeds. The API key is used only for Metra API authentication. The skill does not access, store, or transmit any personal information beyond the API key configured by the user.
modbender