Skip to content

wmata_api_overview.md

Latest commit

 

History

History
141 lines (105 loc) · 4.87 KB

wmata_api_overview.md

File metadata and controls

141 lines (105 loc) · 4.87 KB
Raw

WMATA API Overview — Research Notes

Date researched: 2026-05-05
Source: WMATA Developer Portal (developer.wmata.com), community libraries, Open Data Hub

Developer Portal

Authentication & Rate Limits

Tier Rate Limit Daily Limit
Default (Free) 10 calls/second 50,000 calls/day
Demo Key Limited Subject to change
  • Register at developer.wmata.com to get two API keys per subscription
  • TLS 1.2 required (no older protocols)
  • Recommendation: target ≤9 calls/sec in code to avoid hitting the limit

API Endpoint Categories

Rail (Metrorail)

Endpoint Description Real-time?
StationPrediction.svc/json/GetPrediction/{stationCode} Train arrival predictions Yes
StationPrediction.svc/json/GetPrediction/All All stations predictions Yes
TrainPosition.svc/json/GetTrainPositions Real-time train locations Yes
StationList.svc/json/GetStations Station metadata + coordinates Static
Lines.svc/json/jLines Metro line metadata (RD/BL/YL/OR/GR/SV) Static
Station Routes/Sequences Ordered stations per line Static
Travel Information Time and fare between stations Static
Station Hours First/last train, opening times Static
Rail Incidents/Alerts Service disruptions Yes
Elevator/Escalator Incidents Infrastructure outage status Yes

Bus (Metrobus)

Endpoint Description Real-time?
NextBusService.svc/json/JPredictions?StopID={id} Bus arrival predictions Yes
Bus Routes All routes and metadata Static
Bus Incidents/Alerts Route delays and disruptions Yes
Bus Stops Stop locations and metadata Static

GTFS Data

Feed Format Frequency
GTFS Static (Rail) .zip (CSV tables) Daily
GTFS Static (Bus — Better Bus version) .zip (CSV tables) Daily
GTFS-RT Vehicle Positions Protocol Buffer (.pb) Real-time
GTFS-RT Stop Time Updates Protocol Buffer (.pb) Real-time
GTFS-RT Service Alerts Protocol Buffer (.pb) Real-time

GTFS-RT Vehicle Positions URL: https://api.wmata.com/gtfs/rail-gtfsrt-vehiclepositions.pb

Key Data Fields & Quirks

Train Prediction Min Field

Critical: Min is a STRING, not always an integer. Possible values:

  • Numeric string: "3", "12"
  • "ARR" — arriving
  • "BRD" — boarding
  • "---" — no data
  • Empty string

Always type-check before numeric operations. This is the #1 bug source in WMATA apps.

Train Positions

  • Circuit IDs available but not fully reliable
  • Trains may appear to move backwards (premature circuit triggers)
  • Some trains skip circuits in tracking data

Bus Stop Name Inconsistencies

  • Stop names can differ between API, signage, and in-vehicle displays
  • Do not rely on name matching — use stop IDs

Better Bus Network (Launched June 2025)

  • Route IDs completely changed (new letter-prefix naming convention)
  • 123 new routes replaced old numbering system
  • Limited-stop routes use "X" suffix
  • Historical data comparisons require old→new route ID mapping
  • Apps built before June 2025 need migration

Crowding Data (Post-2024 Addition)

  • Bus and Rail crowding information now available in feeds
  • New field; availability and format may still evolve

Real-Time vs. Static Summary

Real-time (< 30 second latency):

  • Train positions and arrival predictions
  • Bus arrival predictions
  • Service alerts, incidents
  • Elevator/escalator status

Static (Daily or slower):

  • GTFS schedule files
  • Station metadata
  • Route information
  • Fare tables

Community Libraries & Tools

Library Language Notes
pyWMATA Python PyPI: wmata
metro / wmata R CRAN: metro
wmata-api-node Node.js JS wrapper
Home Assistant integration Python DC Metro status tile
ms-metro Various Rail line orchestration

Deprecated: MetroHero (shut down July 1, 2023) — migrate to official WMATA APIs

Open Data Resources Beyond the API