V3 API
The V3 API presents General Transit Feed Specification (GTFS), GTFS Realtime, and MBTA-specific data. It uses the JSON:API format, so you can get started using any of the available libraries.
V3 API Documentation
Read the latest endpoint and resource documentation about available fields, filters, and includes.
Skip to any section below:
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.
Make Basic Calls
The following V3 API 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 | Polylines that describe trip shapes, which can be shown on a map |
| 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, you can filter and sort the list in various ways, and you can 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 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 – 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. |
Use Best Practices
Real-Time Display Guidelines
Real-Time Display Guidelines
The Walnut Avenue bus shelter on Columbus Avenue has a large digital screen that shows the time, the stop name, and the predicted arrival times for the next six buses scheduled to arrive there. The screen also mentions 50%-off Youth Pass fares, and asks riders to tell us how we can improve this screen by going to this web address: mbta.com/walnut-2Learn About API Updates
Developers
Developers
Woman working at her computerUse of MBTA data is governed by the MassDOT Developers License Agreement (PDF, 85.5 KB).
V3 API Documentation
Read the latest endpoint and resource documentation about available fields, filters, and includes.