V3 API

The V3 API provides access to MBTA schedules, alerts, and realtime information. It uses the JSON:API format, so you can get started using any of the available libraries.

Learn more about the JSON:API specification

MBTA V3 API Portal

Request a key, read endpoint and resource documentation, and explore the API.

Request an API Key

We recommend using a V3 API key early in your development process. A valid key is required to make a default of 1,000 requests per minute, control the version, and stream requests.

Request a free key

Make Basic Calls

The V3 API data model is based on the General Transit Feed Specification (GTFS) and GTFS Realtime, where applicable. The following calls are available. To read endpoint documentation for a call, click its link:


Call	Description
Call	/alerts	Description	Communications to riders about disrupted MBTA operations
Call	/facilities	Description	Amenities at stops, such as elevators, escalators, parking lots, and bike racks
Call	/lines	Description	Lines for all modes (for example, `line-Green`)
Call	/predictions	Description	Predicted arrival/departure times
Call	/routes	Description	Routes for each line (for example, `Green-B`)
Call	/route_patterns	Description	Possible patterns of travel for each route
Call	/schedules	Description	Scheduled arrival/departure times (`stop_time`)
Call	/services	Description	Dates when trips occur
Call	/shapes	Description	Stops and maps for routes and their patterns
Call	/stops	Description	Places where riders board a vehicle, disembark from a vehicle, or navigate a station
Call	/trips	Description	Movement of vehicles from one route end to the other
Call	/vehicles	Description	Vehicle positions, including direction, latitude, and longitude

Each call returns the object described. Following the JSON:API standard, options are provided to filter and sort the list in various ways, and to include other objects with related information.

Filter Data

The following examples of filtering use the /routes call. To test a call, click its link:


Call	Description
Call	/routes	Description	Retrieves a list, in the `data[]` object, of all routes
Call	/routes ?filter[type]=0,1	Description	Retrieves only the routes with a route type of 0 or 1 (subway)
Call	/routes ?filter[stop]=place-north	Description	Retrieves only the routes that have trips stopping at the stop, `place-north` (North Station)
Call	/routes ?filter[type]=0,1 &filter[stop]=place-north	Description	Combines the filters above to retrieve only subway trips stopping at North Station
Call	/routes/Orange	Description	Retrieves only the route with `route_id` Orange

Include Relationships

An arrival time doesn't mean much unless you know where the vehicle is arriving and where it's going next. Some objects are defined largely by their relationship to other objects. Those other objects can be included in the results, and you can nest included resources.

The following examples of including use the /schedules call with the same filters. To test a call, click its link:


Call	Description
Call	/schedules ?filter[min_time]=14:00 &filter[max_time]=14:30 &filter[stop]=17094	Description	Returns a selection of scheduled stops (`stop_times`), which contains the `route_id`, `trip_id`, and `stop_id`, but no information about the corresponding trip, route, or stop
Call	/schedules ?include=route &filter...	Description	Includes each route object referenced by a schedule object, returning the route name, mode, color, etc. The included values are in an `include[]` object and can be looked up from the schedule by their type and ID.
Call	/schedules ?include=route,trip,stop &filter...	Description	Includes the routes as well as the trips and stops
Call	/schedules ?include=prediction &filter...	Description	Includes realtime predictions (if any) currently being made for the returned scheduled times. In this example URL, you're only likely to see predictions if you make the call around 1:30 – 2:30 PM ET.

The following example returns predictions with useful information about their related stops. To test the call, click its link:


Call	Description
Call	/predictions ?filter[stop]=place-sstat &filter[direction_id]=0 &include=stop	Description	Returns predictions from South Station with `direction_id` 0. Each prediction has a relationship with a stop, which corresponds to the platform where the vehicle will be. The ID of the related stop can be cross-referenced with the included stops to get useful information, such as the `platform_code` from which the vehicle for the prediction will leave.