Best Practices

If you don’t know where along a route a rider is traveling, filtering only by their origin stop (see example) is likely to miss relevant alerts at other stops along the line. In that case, you should also query for alerts on the entire route (see example) and incorporate them.

The same recommendation applies to implementations where the filtering of the alerts to show happens on the client side. You want to add the alerts where any informed entity includes the relevant route. Even if an alert is about a specific stop, it may affect your riders.

When you do have the information about the rider's entire trip (where they are leaving from and where they are going), you still should consider the alerts on the stops along their route. For example, there might be an alert about shuttles replacing regular service somewhere in the middle of their trip. You can query for multiple stops by comma-separating them in the filter (see example).

You can also use the activity field of the Informed Entity to better filter to those alerts. 

• For stops where the rider boards a vehicle (even transfers), filter for the "BOARD" activity.
• For stops where the rider gets off a vehicle (even transfers), filter for the "EXIT" activity.
• For stops the rider travels through, filter for the "RIDE" activity.
• If the user requests accessible trips, filter for the "USING_WHEELCHAIR" activity.

The documentation for AlertResource has more detail on other types of activities.

Alerts with a severity of 1 are informational. They can receive a more muted visual treatment, if possible, compared with more severe alerts.

Predictions may have an associated `schedule`, which represents the stop as it was originally scheduled to occur. The prediction can be thought of as a realtime update to the schedule; the `schedule_relationship` attribute indicates the nature of the update. Its possible values, and their meanings, are listed in the PredictionResource section of the API documentation.

Note: Predictions may not have a `schedule`, indicating we know a vehicle is running on the route but cannot match it to a scheduled trip.

In general, schedules should be ignored when displaying realtime predictions for rapid transit routes (`route_type` 0 and 1). Schedules are useful for time periods beyond when we have realtime predictions available.

Predictions and schedules may include an `arrival_time`, a `departure_time`, both, or (only for predictions) neither. These are the rules for when a time is present:

• The departure time is present if, and only if, it's possible for riders to board the associated `vehicle` at the associated `stop`. A null departure time is typically seen at the last stop on a trip.
• The arrival time is present if, and only if, it's possible for riders to alight from the associated `vehicle` at the associated `stop`. A null arrival time is typically seen at the first stop on a trip.
• Commuter Rail predictions with neither a departure time nor arrival time often have a status field with their boarding status. Depending on your use case, these predictions may be discarded, or the status may be displayed verbatim to the user (see the “Status Field” section below).
• Predictions with no arrival time, departure time, nor status indicate the vehicle will not make the scheduled stop. The `schedule_relationship` field may explain why.

In general, we recommend not displaying predictions with null departure times, since riders will not be able to board the vehicle. If both arrival and departure time are present, the arrival time is likely to be more useful to riders.

Predictions may have a free-text `status` field, which is synonymous with the GTFS Realtime`boarding_status` field. If present, we recommend displaying this directly to riders in place of the arrival or departure time, since it may indicate a situation that affects the accuracy of the prediction (for example, a train stopped unexpectedly between stations). Status strings are English-language and have no maximum length, though they are typically kept short for display on signage.

The most popular way to display prediction data for a given stop is a countdown of how many minutes away the next few vehicles are, with destinations (for example, "Ashmont" or "Braintree" for the Red Line). These are the rules we follow on the MBTA website and station signs.

The destination component is the `headsign` attribute of the `trip` associated with the `vehicle` of the prediction. The countdown component is determined by following these rules in order, stopping at the first applicable “display” or “do not display” instruction:

• If`status` is non-null:
  • Display this value as-is.
• If`departure_time` is null:
  • Do not display this prediction, since riders won’t be able to board the vehicle.
• Calculate the number of seconds until the vehicle reaches the stop, by subtracting the current time from the arrival time (if available) or the departure time (if not); call this value "seconds."
• If seconds < 0:
  • Do not display this prediction, since the vehicle has already left the stop.
• If seconds <= 90, and the `status` of the associated `vehicle` is "STOPPED_AT", and the vehicle’s `stop` is the same as the prediction’s `stop`:
  • Display "Boarding" (abbreviated as "BRD").
• If seconds is <= 30:
  • Display "Arriving" (abbreviated as "ARR").
• If seconds is <= 60:
  • Display "Approaching" (abbreviated as "1 min").
• Round the seconds value to the nearest whole number of minutes, rounding up if exactly in-between; call this value "minutes."
• If minutes > 20:
  • Display “20+ minutes” (abbreviated as “20+ min”).
• Display the number of minutes followed by "minutes" (abbreviated as "min"). For example:
  • Up to 89 seconds: "1 minute" or "1 min"
  • 90 to 149 seconds: "2 minutes" or "2 min"
  • 150 to 209 seconds: "3 minutes" or "3 min"