V3 API
More from Developers
Select from the list below to learn more about the information and tools available for developers interested in MBTA data.
About the V3 API
The new V3 API provides fast, easy access to MBTA schedules, alerts, and real-time information.
- The V3 API uses the JSON API format, so you can get started quickly using any of the available libraries
- V3 API documentation is available using Swagger
You can try it out without a key, but we strongly recommend using a key early in the development process. Keys are available for free at api-v3.mbta.com.
Basic Calls
The V3 API data model is based on GTFS and GTFS-realtime where applicable. The following calls are available:
- alerts
- facilities - elevators, escalators, and (coming soon) parking lots, bike racks, etc.
- predictions - predicted arrival/departure times
- routes
- schedules - scheduled arrival/departure times (stop_time)
- shapes - stops and maps for branches, including route variations
- stops
- trips
- vehicles - vehicle positions
Each call returns the object described. Following the JSON API standard, options are provided to filter or sort the list in various ways, and to include other objects with related information.
Filter
The following examples of filtering use the routes call:
- /routes retrieves a list, in the data[] object, of all routes.
- /routes?filter[type]=0,1 retrieves only the routes with a route type of 0 or 1 (subway)
- /routes?filter[stop]=place-north retrieves only the routes that have trips stopping at the stop place-north (North Station)
- /routes?filter[type]=0,1&filter[stop]=place-north combines the filters above to retrieve only subway trips stopping at North Station
- /routes/Orange retrieves only the route with `route_id="Orange"`
Include
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 as well.
The following examples of "including" use the schedules call:
- schedules?filter... 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.
- schedules?include=route&filter... includes each route object referenced by a schedule object, providing the route name, mode, color, etc. The included values are in an `include[]` object and can be looked up from the predictions by their type and id.
- schedules?include=route,trip,stop&filter... includes the routes as well as the trips and stops.
- schedules?include=prediction&filter... includes real-time 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 PM-2:30 PM EST.
This is an example to obtain predictions with useful information about the stops they are related to:
- predictions?filter... returns predictions from South Station with direction_id 0. Note the "relationships" fields for each prediction; each prediction has a relationship with a stop which corresponds to the platform the train will be at. The id of the related stop can be cross referenced with the included stops to obtain useful information such as the platform_code that the vehicle for the prediction will be leaving from.
For more information, see the V3 API Swagger documentation and get a key at api-v3.mbta.com.
Use of MBTA data is governed by the MassDOT Developers License Agreement.