transitmatters-py

MBTA performance data from the TransitMatters Data Dashboard, as Python objects: travel times, headways, dwells, ridership, service levels, delays, speed restrictions, and alerts.

pip install transitmatters

from transitmatters import TransitMatters

tm = TransitMatters()

# Every southbound Red Line trip from Alewife to Braintree on March 4, 2025
trips = tm.travel_times("2025-03-04", from_stop="70061", to_stop="70105")
print(trips[0].dep_dt, trips[0].travel_time_sec)

Dates can be datetime.date objects or "YYYY-MM-DD" strings, and date ranges include both ends. Parameters that take IDs accept one string or a list.

Which method do I want?

What happened on one day. Each item is a single event.

Trends over a date range. Each item summarizes one day, week, or month.

Right now, and system-wide.

Finding IDs

Each kind of ID has its own format, and some endpoints spell the same line differently. Check this table before guessing:

TransitMatters.routes lists every route ID. TransitMatters.stops lists the stations on a route, with the stop ID of each platform by direction:

red = tm.stops("Red")
print(red.direction.to_dict())  # {'0': 'northbound', '1': 'southbound'}
for station in red.stations[:3]:
    print(station.stop_name, station.stops.to_dict())
# Alewife {'0': ['70061'], '1': ['70061']}
# Davis {'0': ['70064'], '1': ['70063']}
# Porter {'0': ['70066'], '1': ['70065']}

Platforms have separate IDs for each direction, so from_stop and to_stop must both be platforms for the direction you're traveling. Southbound from Davis to Porter is from_stop="70063", to_stop="70065".

A stop ID that doesn't exist isn't an error; you just get an empty list back.

Working with pandas

Every result is a model object (see transitmatters.models), and every model has to_dict():

import pandas as pd

events = tm.headways("2025-03-04", stop="70061")
df = pd.DataFrame([e.to_dict() for e in events])
df["current_dep_dt"] = pd.to_datetime(df["current_dep_dt"])

• Timestamps are Eastern local time, formatted YYYY-MM-DDTHH:MM:SS with no offset.
• to_dict() uses the API's field names. A few differ from the Python attribute names, e.g. min and 25% instead of min_ and field_25.
• When a response wraps its list in a field, such as scheduled_service(...).counts or speed_restrictions(...).zones, build the DataFrame from that field.

Errors

When the API rejects a request, methods raise transitmatters.APIError:

from transitmatters import APIError

try:
    tm.stops("Purple")
except APIError as e:
    print(e.status_code, e.message)  # 404 Route 'Purple' not found

Async

transitmatters.AsyncTransitMatters has the same methods, as coroutines. It's useful for fetching many days at once. In Jupyter you can await directly in a cell.

import asyncio
from transitmatters import AsyncTransitMatters

async def main():
    async with AsyncTransitMatters() as tm:
        days = ["2025-03-03", "2025-03-04", "2025-03-05"]
        return await asyncio.gather(*(tm.headways(d, stop="70061") for d in days))

per_day = asyncio.run(main())

Development

uv sync
uv run pytest
uv run python scripts/docs.py  # preview the API docs at http://localhost:8080

The API docs are built from this README and the docstrings in src/transitmatters/, and are published to GitHub Pages on every push to main.

src/transitmatters/_generated/ is generated from the upstream OpenAPI spec by openapi-python-client; don't edit it by hand. A weekly workflow syncs the spec and opens a PR (see scripts/sync_spec.py). The public API lives in src/transitmatters/client.py.