Skip to main content

Migrating from API-V2 to the V3 API

API-V2 is deprecated and will be operated through April 2018. Developers using API-V2 should migrate to either GTFS-realtime or the V3 API. See frequently asked questions to learn more about choosing between them and this migration. 


API Keys

Your API key for API-V2 won't work for the V3 API. Each API has its own set of keys accessed through its own portal with its own user accounts. You can request your V3 API key here and continue to manage your API-V2 keys here. You can start working with the V3 API without a key, but we strongly recommend you get one. Keys are free and have a much higher initial usage limit compared to API V2 (1,000 requests per minute instead of 10,000 per day).

Swagger and JSON API

The V3 API is documented using Swagger. If you haven't used Swagger-based documentation before, take a look just to see how it's organized. When you're looking at the calls, don't forget to scroll to the bottom and look at the models too. The documentation of the calls is entirely interactive, and you may be able to use the swagger.json in your development environment.

The V3 API uses the JSON API standard. To start using the API quickly in your application, you can use any of the available libraries. The filtering and relationship functions described below are all part of the JSON API standard.

If you haven't, take a look at the "basic calls," "filter" and "include" sections of the V3 API introduction.

Example: Arrival Time for Service Near Me

Suppose you wanted an application that would use the user's latitude and longitude to show them the nearest stops, the upcoming predicted departures from those stops.

API-V2 Approach

  1. Use stopsbylocation to retrieve a list of nearby stops.
  2. Use predictionsbystop (once for each nearby stop) to retrieve real-time prediction times.
  3. Filter out predictions that are arrival-only (prediction of arrival at vehicle's last stop).
    Then, use one schedulebytrip call for each prediction you want to display to see if the stop is the last stop listed for that trip. 

    Or, because that’s a lot of calls, compare strings to see if the trip's trip_headsign starts with the stop's stop_name. That works most of the time. 

    Or, just hope that the customer isn't standing near a terminal, even though they're often the highest-ridership stops and stations.

Total calls: 5-10 or 10-20, depending on approach and number of stops.

V3 API Approach

Instead of searching for stops first and then predictions, simply search for predictions for stops within a geographical area using /predictions with filter[latitude] and filter[longitude]. Then, include stop information with the results to show where the stops are, include schedule information that indicates if a prediction is for the end of a trip, include trip information so there’s destination (headsign) text to show, and include route information.

This is just 1 call: /predictions?filter[latitude]=42.352975&filter[longitude]=-71.055560&include=stop,route,trip,schedule

Each object in data[] is a prediction, and each object in included[] is a route, trip, or schedule (stop_time) that relates to at least 1 prediction. For example, if a prediction's relationships includes stop: {data: {type: "stop", id: "South Station"}} then the prediction is for the stop identified by id "South Station" and more information about that stop can be found in an object in included[].

For each prediction, check the schedule value and exclude the prediction if pickup_type=1 (no pickup available.) This will exclude predictions that are arrival-only.

Total calls: 1.

Cheat Sheet

The best approach to getting information from the V3 API often isn't the same as the best approach from API-V2. It's often possible to replace 2-3 (or even 5-10) calls with just 1. But if you just need to replace an API-V2 call with a V3 API call, here's a guide:

API-V2 CallV3 API CallNotes
API-V2 CallroutesV3 API Call/routesNotesIncludes much more information. Sorted for presentation by default.
API-V2 CallroutesbystopV3 API Call/routesNotesUse filter[stop]
API-V2 CallstopsbyrouteV3 API Call/stopsNotesUse filter[route]. In the case of child stops, parent will be returned.
API-V2 CallstopsbylocationV3 API Call/stopsNotesUse filter[latitude], filter[longitude], and optional filter[radius].
API-V2 CallschedulebystopV3 API Call/scheduleNotesUse filter[stop] and include=trip.
API-V2 CallschedulebyrouteV3 API Call/scheduleNotesUse filter[route] and include=trip. 
API-V2 CallschedulebyroutesV3 API Call/scheduleNotesUse filter[route] and include=trip. 
API-V2 CallschedulebytripV3 API Call/scheduleNotesUse filter[trip] and include=trip.
API-V2 CallpredictionsbystopV3 API Call/predictionsNotes

Use filter[stop] and include=trip,schedule.

Or try /schedule with include=prediction.

API-V2 CallpredictionsbyroutesV3 API Call/predictionsNotes

Use filter[route] and include=trip,schedule.

Or try /schedule with include=prediction.

API-V2 CallpredictionsbyrouteV3 API Call/predictionsNotes

Use filter[route] and include=trip,schedule.

Or try /schedule with include=prediction.

What Was in API-V2 that Isn't in the V3 API?

The following is a list of features that can be found in API-V2 but not the V3 API, and recommendations:

FeatureJSONPRecommendationUse CORS (Cross-Origin Resource Sharing), a more secure solution to the same-origin policy problem. 
FeatureXMLRecommendationUse a JSON API library and get started without even having to think about the format. 
FeatureRate limit email warningRecommendationWe may add tools to help you manage your API usage in the future. The default limit for a new API key is 1,000 requests per minute so there's less need to monitor usage closely. 
Featuremode_nameRecommendationroute_type and route_desc serve a similar purpose; if you need the exact values from before, look them up using mode[route_type] where mode = {0: "Subway", 1: "Subway", 2: "Commuter Rail", 3: "Bus", 4: "Boat"}
FeatureAlert headers in prediction callsRecommendationMake separate calls for predictions and alerts.
Featureroute_hideRecommendationA "hidden" route (such as those that run a single trip once a day) will not be returned unless applicable. 

Use of MBTA data is governed by the MassDOT Developers License Agreement.