subway-info

Subway Info

Overview

Real-time NYC transit information covering subway, bus, ferry, and commuter rail (LIRR/Metro-North). Covers all 496 subway stations, 16,000+ bus stops, NYC Ferry landings, and LIRR/Metro-North stations.

When to Use

• Checking real-time train arrivals at a station
• Getting current service alerts and delays
• Searching for subway stations by name or line
• Planning trips between subway stations
• Checking bus arrivals and routes
• NYC Ferry schedules and alerts
• LIRR and Metro-North departures
• Commute planning and schedule checking

CLI Tool (Preferred)

If subway-info CLI is available, prefer it over raw curl — it handles retries, auth, and outputs token-efficient text by default.

Install

# From the mta-mcp repo
npm run build:cli
# Binary at ./dist/subway-info

# Or run directly
npm run cli -- arrivals --station 127

Subway Commands

subway-info arrivals --station 127 --line 1 --direction N --limit 5
subway-info alerts --line A
subway-info stations --query "times square"
subway-info trip --from 127 --to 631
subway-info status --line L

Bus Commands

subway-info bus arrivals --stop 402940 --route M1
subway-info bus alerts --route M1
subway-info bus stops --query "5th ave" --borough Manhattan
subway-info bus route --route M1

Ferry Commands

subway-info ferry arrivals --landing <id>
subway-info ferry alerts
subway-info ferry landings --query "wall street"
subway-info ferry routes

Rail Commands (LIRR / Metro-North)

subway-info rail departures --station <id> --system LIRR
subway-info rail alerts --system MNR
subway-info rail stations --query "penn" --system LIRR
subway-info rail station --station <id>

Global Options

--json          Print raw JSON instead of compact text
--api-key <key> Override $SUBWAY_INFO_API_KEY
--base-url <url> Override https://subwayinfo.nyc

REST API

All data endpoints use POST with JSON body. Base URL: https://subwayinfo.nyc

Rate Limits

Tier	Requests/Min	Authentication
Anonymous	10	None (IP-based)
Free	60	X-API-Key header
Standard	300	X-API-Key header
Premium	1000	X-API-Key header

Subway Endpoints

Get Arrivals

curl -s -X POST https://subwayinfo.nyc/api/arrivals \
  -H "Content-Type: application/json" \
  -d '{"station_id": "127", "line": "1", "direction": "N", "limit": 5}'

Parameter	Type	Required	Description
station_id	string	Yes	Station ID (use search to find)
line	string	No	Filter by line (e.g., "1", "A", "F")
direction	"N" | "S"	No	N=uptown/Bronx, S=downtown/Brooklyn
limit	number	No	Max arrivals (default: 10)

Get Alerts

curl -s -X POST https://subwayinfo.nyc/api/alerts \
  -H "Content-Type: application/json" \
  -d '{"line": "A"}'

Parameter	Type	Required	Description
line	string	No	Filter by line
alert_type	string	No	Filter by type (e.g., "Delays", "Planned Work")

Search Stations

curl -s -X POST https://subwayinfo.nyc/api/stations \
  -H "Content-Type: application/json" \
  -d '{"query": "union square"}'

Parameter	Type	Required	Description
query	string	No	Station name search
line	string	No	Filter by line
limit	number	No	Max results (default: 10)

Get Station Info

curl -s -X POST https://subwayinfo.nyc/api/station \
  -H "Content-Type: application/json" \
  -d '{"station_id": "127"}'

Plan Trip

curl -s -X POST https://subwayinfo.nyc/api/trip \
  -H "Content-Type: application/json" \
  -d '{"origin_station_id": "127", "destination_station_id": "631"}'

Bus Endpoints

POST /api/bus/arrivals   {"stop_id": "402940", "route": "M1", "limit": 5}
POST /api/bus/alerts     {"route": "M1"}
POST /api/bus/stops      {"query": "5th ave", "borough": "Manhattan"}
POST /api/bus/route      {"route_id": "M1"}

Ferry Endpoints

POST /api/ferry/arrivals  {"landing_id": "<id>", "route": "<route>"}
POST /api/ferry/alerts    {"route": "<route>"}
POST /api/ferry/landings  {"query": "wall street"}
POST /api/ferry/routes    {}

Rail Endpoints (LIRR / Metro-North)

POST /api/rail/departures {"station_id": "<id>", "system": "LIRR"}
POST /api/rail/alerts     {"system": "MNR", "branch": "Hudson"}
POST /api/rail/stations   {"query": "penn", "system": "LIRR"}
POST /api/rail/station    {"station_id": "<id>"}

Health Check

GET /health

Common Station IDs

Station	ID	Lines
Times Sq-42 St	127	1, 2, 3, 7, N, Q, R, W, S
Grand Central-42 St	631	4, 5, 6, 7, S
14 St-Union Sq	L03	L, 4, 5, 6, N, Q, R, W
34 St-Penn Station	A28	A, C, E, 1, 2, 3
Fulton St	A38	A, C, J, Z, 2, 3, 4, 5
Atlantic Av-Barclays Ctr	D24	B, D, N, Q, R, 2, 3, 4, 5

Use subway-info stations --query "..." or /api/stations to find any station ID.

Helper Scripts

./scripts/arrivals.sh "times square"          # Search by name
./scripts/arrivals.sh 127 1 N 5              # By ID with filters
./scripts/alerts.sh A                         # A train alerts
./scripts/trip.sh "times square" "grand central"
./scripts/status.sh L                         # L train status

Error Handling

Status Code	Meaning	Action
400	Bad Request	Check required parameters
401	Unauthorized	Invalid API key
429	Rate Limited	Reduce request frequency or add API key
500	Server Error	Retry with backoff

Best Practices

• Use CLI when available — handles retries, auth, and compact output automatically
• Search first: Find station IDs before calling arrivals
• Filter by line: Narrow arrivals with line parameter for cleaner results
• Cache station IDs: Station IDs are stable; cache them after first lookup
• Respect rate limits: Anonymous tier is 10 req/min; set SUBWAY_INFO_API_KEY for higher limits

Common Pitfalls

Transit data is notoriously tricky. These are real failure modes that catch agents and users regularly.

Outdated Schedule Data (Cached vs Real-Time)

The Problem: Arrival times shown may be cached or stale, especially during heavy traffic or service disruptions.

Why It Happens:

• API responses cache at edge servers for 5-10 seconds to handle load
• Client-side polling without fresh server calls returns stale data
• During service disruptions, arrival predictions revert to scheduled times (not real)

How to Detect & Fix:

# Check data freshness timestamp in response
curl -s -X POST https://subwayinfo.nyc/api/arrivals \
  -H "Content-Type: application/json" \
  -d '{"station_id": "127"}' | jq '.data_timestamp'

# If timestamp is >10 seconds old, force fresh fetch (use new API key or IP to bypass cache)
# Or: add ?nocache=true parameter if API supports it

When This Matters: Real-time trip planning, urgent commutes, tight connections Solution: Always fetch fresh data for time-critical decisions; don't rely on stale responses

Missing Service Alerts (Planned Work, Delays Not Checked)

The Problem: A train arrives in 20 minutes, but there's a planned service change, track work, or delay that the arrivals endpoint didn't surface.

Why It Happens:

• /api/arrivals shows train predictions but doesn't include active alerts
• Planned work (weekends, nights) isn't reflected in real-time predictions
• Delays added mid-journey aren't immediately reflected across all endpoints
• Advisory alerts (e.g., "expect delays") exist but aren't tied to specific arrivals

How to Detect & Fix:

# Always check alerts separately from arrivals
curl -s -X POST https://subwayinfo.nyc/api/alerts \
  -H "Content-Type: application/json" \
  -d '{"line": "1"}' | jq '.[] | select(.type | contains("Planned"))'

# Cross-reference: if planning a trip at 11 PM on Saturday, check alerts first
# Many lines have weekend/night track work that predictions don't catch early

When This Matters: Weekend trips, night commutes, planned service disruptions Solution: Always fetch alerts before planning a trip, not after seeing arrivals

Wrong Station/Line Identification (Name Confusion, Multiple Stations)

The Problem: "Times Square" has 4+ stations; searching gives ambiguous results; agent picks wrong one.

Why It Happens:

• Station names aren't unique (e.g., "14 St" exists 6+ times across the system)
• Multiple lines serve the same physical location but with different IDs (42 St-Times Sq is 127, but 42 St-Port Authority is A09)
• Search returns top 5 results but doesn't disambiguate by line or direction
• User says "Grand Central" but means Grand Central Terminal (multiple LIRR/MNR stations exist)

How to Detect & Fix:

# Search returns ambiguous results
curl -s -X POST https://subwayinfo.nyc/api/stations \
  -H "Content-Type: application/json" \
  -d '{"query": "times square"}' | jq '.results[] | {name, id, lines}'

# Output: Multiple results with overlapping names
# Solution: Filter by line before picking station ID
curl -s -X POST https://subwayinfo.nyc/api/stations \
  -H "Content-Type: application/json" \
  -d '{"query": "times square", "line": "1"}' | jq '.results[0].id'

When This Matters: Multi-line stations, tourist areas, connections between systems Solution: Always filter searches by line if user specifies it; confirm station ID before using it

Reference Table (Ambiguous Stations):

Location	Station Names	Lines	IDs
Times Square Area	42 St-Times Sq, 42 St-Port Authority, 42 St-GCT	1/2/3 vs A/C/E vs 4/5/6/7	127 vs A09 vs 631
14th Street	14 St-Union Sq, 14 St-A/C, 14 St-F/M, 14 St-1/2/3, 14 St-L	Multiple	Multiple
Penn Station Area	34 St-Penn, 34 St-Herald Sq, 34 St-GCT	A/C/E vs B/D/F/M vs 1/2/3	A28 vs B24 vs 307

Time Zone Handling (Schedule vs User Location Time)

The Problem: Schedule shows 5:30 PM arrival, but user is in Pacific time and misreads it as local 2:30 PM.

Why It Happens:

• MTA schedule data is always in Eastern Time (ET) — API doesn't convert
• User's system clock may be different timezone
• Travel time estimates don't account for timezone differences if trip crosses regions
• Schedule responses don't include timezone info; agent must infer

How to Detect & Fix:

# API returns times in ET (no TZ field)
curl -s -X POST https://subwayinfo.nyc/api/arrivals \
  -H "Content-Type: application/json" \
  -d '{"station_id": "127"}' | jq '.arrivals[0].arrival_time'

# Always convert to user's timezone before displaying
# JavaScript example:
const etTime = new Date(arrivalTime); // Interpreted as ET
const userTz = Intl.DateTimeFormat().resolvedOptions().timeZone;
const userTime = etTime.toLocaleString('en-US', { timeZone: userTz });

When This Matters: Remote users, cross-country travel planning, scheduling meetings Solution: Always note that times are in Eastern Time; convert to user's local time when displaying

Weekend/Holiday Schedule Differences (Wrong Assumptions)

The Problem: Monday's train schedule is different from Saturday's; predictions assume weekday service but it's actually a holiday.

Why It Happens:

• MTA runs different schedules for weekdays, Saturdays, Sundays, and holidays
• Arrival predictions are weekday-based by default; weekend schedules are sparse
• Holiday schedules (Thanksgiving, Christmas, New Year's) are completely different
• Some lines have modified service on nights/weekends that predictions don't reflect clearly

How to Detect & Fix:

// Check if today is a holiday or weekend
const today = new Date();
const dayOfWeek = today.getDay(); // 0 = Sunday, 6 = Saturday
const holidays = ["2026-01-01", "2026-07-04", "2026-12-25"]; // NYD, July 4, Xmas
const isSpecialDay = dayOfWeek === 0 || dayOfWeek === 6 || holidays.includes(today.toISOString().split('T')[0]);

if (isSpecialDay) {
  console.warn("Running reduced/modified schedule today. Arrivals may not reflect typical service.");
  // Fetch fresh alerts to see if specific lines have changes
}

When This Matters: Weekend trips, holiday travel, late-night commutes Solution: Check day-of-week and holiday calendar; verify alerts if weekend/holiday

MTA API Version Drift (Deprecated Endpoints, Breaking Changes)

The Problem: Old code uses /arrivals endpoint but MTA deprecated it in favor of a new schema that returns different field names.

Why It Happens:

• MTA occasionally updates API schemas without backward compatibility
• Field names change (e.g., arrival_time → estimated_arrival_time)
• Response structure reorganizes (nested vs flat)
• Version mismatches between live API and local documentation

How to Detect & Fix:

# Check API version in response headers
curl -s -i -X POST https://subwayinfo.nyc/api/arrivals \
  -H "Content-Type: application/json" \
  -d '{"station_id": "127"}' | grep -i 'api-version'

# If response structure is unexpected, check API docs at subwayinfo.nyc/docs
# Parse defensively: use `.get()` and provide defaults
const arrival_time = response.arrivals?.[0]?.estimated_arrival_time 
  ?? response.arrivals?.[0]?.arrival_time 
  ?? "Unknown";

When This Matters: Long-running services, production dashboards, archival code Solution: Monitor API version headers; test after MTA updates; use defensive parsing

Rate Limit Surprises (Exceeding Quota During Bursts)

The Problem: You're on the Free tier (60 req/min), but a popular line gets heavy traffic and you blast 200 requests in 10 seconds checking multiple stations.

Why It Happens:

• Rate limits are per-minute buckets; bursts within a minute can exceed quota
• Checking many stations or lines simultaneously exceeds limit quickly
• API returns 429 but doesn't queue requests — they fail immediately
• Error recovery (retry loops) can cascade and exceed limits further

How to Detect & Fix:

# Monitor for 429 responses
curl -s -X POST https://subwayinfo.nyc/api/arrivals \
  -H "Content-Type: application/json" \
  -d '{"station_id": "127"}' \
  -w "\nHTTP Status: %{http_code}\n"

# If 429: Implement exponential backoff
async function fetchWithRetry(url, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url);
    if (response.status !== 429) return response;
    const retryAfter = response.headers.get('Retry-After') || (2 ** i);
    await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
  }
  throw new Error("Rate limited after retries");
}

When This Matters: Dashboards, multi-station queries, production load spikes Solution: Serialize requests or batch them; monitor rate limit headers; use API key for higher quotas

Resources

• Subway Info Website
• API Documentation
• MTA Developer Resources