V3 API change: "connecting stops" replaces "recommended transfers"

[Developer at MBTA]

Hi developers,

Recently we added a connecting_stops relationship to Stop resources in the V3 API. This returns stops that should be considered "connections" to or from the stop, but are not a parent, child, or sibling of the stop.

The use case we developed this for is showing "connecting" routes on line diagrams and real-time info screens. For example: Mass Ave @ Newbury St (stop ID 93) is a stop on the 1 bus route. Although this stop is steps away from an entrance to Hynes Convention Center station (place-hymnl), it is correctly not among the child_stops of that station, because it is not within the station structure. But ideally, since MBTA maps and signage indicate a "connection" to the 1 bus at Hynes, an app using the API should have some way of showing this too. connecting_stops makes this information available.

If you've used the recommended_transfers relationship this may sound familiar, and in fact connecting_stops is a more "complete" version of the same concept. While recommended transfers were hand-authored and only covered a small (and somewhat arbitrary) set of stations, connecting stops are auto-generated for all stations in the system, with an overlay of manual corrections.

Related changes

V3 API: recommended_transfers is now an undocumented (soft-deprecated) alias for connecting_stops. This may be removed in a future API version; as always, you can avoid unexpected breaking changes by following our guidance on Versioning.

GTFS: The old "recommended transfers" (type 0 in transfers.txt) have been removed from the feed. We determined this was likely not the correct way to represent what we're now calling "connecting stops", and it had unintended consequences on trip planning. For now, connecting stops are synthesized within the API.

Example usage

Expanding on the Hynes Convention Center example above, suppose we want to display “connecting routes” for this stop (place-hymnl). First, to get all the relevant stops, we request:

/stops/place-hymnl?include=child_stops,connecting_stops

To make this a generic query for any stop, we could also include parent_station.child_stops and parent_station.connecting_stops. Then, if the requested stop has a parent station, its child stops and connecting stops will also be included.

Now we have stops, but what we want is routes. For this we need to collect the IDs of all stops returned in the included for the above request, and make a second request:

/routes?filter[stop]=79,93

This will return routes that have trips which serve these stops; in this case, the 1 and 57 bus routes.

Note it's not yet possible to do this in a single request, and as a result N+1 requests are needed in e.g. "line diagram" situations where the connecting routes of multiple stops are desired (though this was already the case even if only using child stops to determine connections). The stop filter used here also has a limitation that it will not return a route if all the relevant trips are "atypical", such as shuttle routes. We're looking into fixing these limitations, since they also impact our own use cases.

Tips and caveats

• Connections are not formed between a parent station and its child stops, or between stops that are children of the same parent station, since this would be redundant with the parent_station and child_stops relationships. We recommend using these in combination with connecting_stops in the typical case where you want to include "connections" within stations.

• Connections are currently only formed between parent stations and "standalone" stops (without a parent station). In particular this means child stops never have connections. If you have a mix of stop types and want to get all connecting stops, including from parent stations, use e.g. include=connecting_stops,parent_station.connecting_stops.

• Connections are currently only formed between "standalone" stops if they are also connected to a common parent station. If e.g. two bus routes cross each other, but the crossing is not near a parent station, their stops will not be "connected" (despite a connection being announced on the buses). We may add such connections in the future.

Feedback

Our goal is for connecting_stops to be a close match with (or at least a superset of) the route "connections" indicated on hand-authored MBTA signage, maps, guides, etc. If you notice a case where it doesn't match, or just doesn't seem to make sense, we'd like to hear about it! Feel free to reply in this thread with the details, or send us an email.