MTA API v3

Real-time NYC subway arrivals API with async concurrent feed fetching.

Key Differences from v2

• Concurrent fetching: All 8 MTA feeds fetched in parallel using asyncio.to_thread()
• Async cache: Uses asyncio.Lock to prevent concurrent refresh storms
• Lazy refresh: Cache updates on first request after expiry

Performance

• Sequential fetch (v2): ~2-4 seconds
• Concurrent fetch (v3): ~500ms-1s

Quick Start

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload

API Endpoints

Same as v2 - see /docs for OpenAPI documentation.

Docker

docker build -t mta-api-v3 .
docker run -p 8000:8000 mta-api-v3

Deploy to Fly.io

Fly.io is recommended for v3 since it supports persistent servers with the async caching model.

First-time setup

# Install flyctl
curl -L https://fly.io/install.sh | sh

# Login
fly auth login

# Launch app (creates fly.toml)
cd mta-api-v3
fly launch --name mta-api-v3 --region ewr --no-deploy

# Deploy
fly deploy

fly.toml

If you need to create it manually:

app = "mta-api-v3"
primary_region = "ewr"  # Newark, close to MTA servers

[build]
  dockerfile = "Dockerfile"

[http_service]
  internal_port = 8000
  force_https = true

[[http_service.checks]]
  path = "/"
  interval = "30s"
  timeout = "5s"

Useful commands

fly status              # Check app status
fly logs                # View logs
fly ssh console         # SSH into the container
fly scale count 2       # Scale to 2 instances
fly secrets set KEY=val # Set environment variables

CLI

Query subway data from the command line. Output is JSON by default.

# Setup
source venv/bin/activate

# List all stations
python -m mta.cli stations

# Search stations by name
python -m mta.cli stations -q "Times Sq"

# Get station by ID (with arrivals)
python -m mta.cli stations 127

# Get multiple stations
python -m mta.cli stations 127,A32

# Search by location
python -m mta.cli stations --lat 40.7580 --lon -73.9855

# List all routes
python -m mta.cli routes

# Get stations on a route
python -m mta.cli routes A

# Find next trains from a station
python -m mta.cli find "Times Sq"

# Find specific route from a station
python -m mta.cli find "Times Sq" -r A

# Human-readable output (--pretty goes before the command)
python -m mta.cli --pretty stations 127

MCP Server

Run as a Model Context Protocol server for AI assistants:

python -m mta.mcp

Available Tools

Claude Desktop Configuration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mta-subway": {
      "command": "python",
      "args": ["-m", "mta.mcp"],
      "cwd": "/path/to/mta-api-v3"
    }
  }
}