1. Home
  2. Developer resources
  3. How to use GTFS Alerts to create a "Status Box"

How to use GTFS Alerts to create a "Status Box"

Updated Aug 14, 2023
We are moving away from this UI, but here's how to make one with our data.


Service Status is a UI pattern that the MTA embraced beginning with the redesign of mta.info in January, 2010.  It involves listing all of the routes (or groups of routes, for subways and buses) and assigning each a "status". It's a simple and easily scannable pattern, so even though we're moving away from it it remains popular.

The MTA's original Service Status box grouped subway lines by Manhattan trunk (e.g. grouping the 1, 2, and 3 lines together) and assigned each group a status based on the most severe status of all alerts affecting the lines within that group.

MYmta introduced a variant that groups lines by status, rather than by trunk group, which allows for more granular messaging. Often, there are delays on only one line of a trunk so it was misleading to show all three together labeled with a single issue. 



A screenshot of a colorful table UI element from TFL's website. On the left side are various rail line names and on the right side are descriptions of the service on those lines.
TFL Service Status Box
A screenshot of a colorful MTA UI element. Subway lines are grouped by color on the left with service status' on the right.
Legacy MTA Service Status Box
Screenshot of a colorful UI element. Headings on the left  indicate service status while underneath each one are the subway bullets for each affected line.
MYmta Service Status Box

Why we are moving away from the Service Status box

The Service Status box is simple, but it's reductive. The A train is roughly 32 miles long, so a delay which affects passengers on part of the line may not be a concern for riders in other areas. Consequently, describing the entire line as "delayed" doesn't make sense. In addition, as we look at the main open data standard for service alerts, we see that the format supports tagging more than just routes. It also includes agencies, stations, and even individual trips. While routes are really helpful, maybe we want to think more broadly. 

We are moving towards an "Alerts" framework, which we think more accurately describes everything happening on a line. Rather than making an editorial decision about how to describe the entirety of the A train, MTA communications staff now publish alerts for every incident that impacts service along the line. By showing more of those alerts, we hope to give riders a more complete picture of how their buses and trains are running. The communications team is also thinking more broadly about new platforms. We have tens of thousands of digital screens on subways, buses, and trains. We have apps that make it much easier to drill down to stations or lines or serve up geotargeted push alerts. A broad overview like the Service Status box is helpful for some, but most riders tell us they want contextual information. We can't provide that with just the Service Status box. 

At present, we retrofit alerts into a Service Status box UI on the homepage, but we will be moving towards a more map-centric homepage in the future, so rather than alerts being front and center, alerts will be served up alongside other kinds of transit information (arrivals, departures, elevators, etc) when riders select a stop or route.

Building service status box logic (this is assuming you want to sort by route)

Even though we are moving away from it, you may want to replicate the Service Status box in your own application. It's a great way to show a simplified, system-wide view. However, because our underlying service alert data has changed, front-end consumers need apply some logic. 

  1. Sign up for an account at the MTA's API gateway. Follow the instructions there for using an API token to access the Alerts API.
  2. Query the alerts API. 
  3. Perform the following steps for each line or group of lines which you want to display in your Service Status box:
    1. Extract all alerts matching the route ID or route IDs for the current group, then filter these alerts for those where the active_period contains the current time. Make sure you also consider the value of the display_before_active field. 
    2. If no alerts meet this criteria for a given line or group of lines, show a fallback message. We had used "Good Service" but now we recommend “No Active Alerts” for subways and buses and "On or Close" for the railroads. There can be minor service disruptions that don't have alerts associated with them. 
    3. If there are alerts, determine which alert in the group has the largest integer in sort_order.
    4. Display the alert_type for the alert meeting the criteria above as the "service status" 
    5. If your provides some type of drill-down for statuses, we recommend showing all currently active alerts on the following page, sorted by sort_order.

Fields that control display

The full API documentation for the alerts API is here. The full API To have service alerts appear in a “status box”-style result from our GTFS-rt alerts feed, consumers need to use these fields in the Alert entity:

  • InformedEntity.route_id: Each service line has a unique route ID corresponding to the routes.txt file in our base GTFS (eg, 1 train, F train, B36 bus). 
  • InformedEntity.MercuryEntitySelector.sort_order: Each Alert type has a corresponding number that indicates its “severity” compared to other alerts. Larger numbers are more severe than lower numbers (eg, Slow Speeds – 16, Delays – 22, Suspended – 39)
  • MercuryAlert.alert_type: A string with the alert category that basically serves as the title of the Alert. (eg: Delays, Part Suspended, Planned – Express to Local)
  • Alert.active_period: Provides the time (or times) a given alert is “in effect”. 
  • MercuryAlert.display_before_active: Provides the number of seconds before something should appear in the status box. For example, an alert about planned work might start at 9 pm but service changes actually begin an hour or so earlier as we get equipment into position. If this is null, we don't show alerts in a Service Status box. It will be blank for minor alerts like station staircase repairs.