Service Alerts

Providing a comprehensive and accurate service alerts feed is a key part of delivering accurate information about transit service to riders. Knowing about stop closures, detoured routes, cancelled service, and significant delays in advance can save riders time and frustration.

The GTFS real-time format includes a standardized format for service alerts. Using this format allows trip planners, including Transit, to provide alternatives and inform riders of relevant incidents.

In order to display relevant alerts to riders, we need to know the most important details of the alert, including, what transit services are affected, how service is disrupted, why they are affected and when the service alert applies. This article will cover each part in turn.

Note: We strongly encourage agencies to produce a quality GTFS Real Time feed for service alerts. If you only have a different API format available, please reach out to data@transitapp.com for help.

Entity selectors

Entity selectors specify what is impacted by the disruption. Multiple selectors can be used for one service alert, and each selector can specify entities such as the route, stop, trip, and/or agency affected. Each selector applies the combination (intersection) of the entities specified. All id’s must match the GTFS Static data.

Transit supports agency, route, route_type, stop, and trip selectors:

Agency_id selectors will appear on each route that belongs to that agency
Route_type selectors will apply to each route with that type.
Route selectors will apply to the entire route: every trip, and stop served by that route.
Stop_id selectors will apply that alert to the relevant GTFS stop – this includes, stations, platforms and entrances. You may, for example, publish an accessibility alert on an entrance that is temporarily inaccessible to wheelchair users.
Alerts with entities with a trip_id will appear next to the impacted trip(s).
If an alert affects all stops on a route, do not specify entity selectors for every stop. Instead, specify only the route_id as the entity. Similarly, do not specify every trip_id if the alert affects all trips in the time range.
Choose the most specific stop entity possible; we support entrances, stations, platforms
For station closures, only specify the stop_id’s that are completely closed for passenger service. For example if Station B is closed but riders can get on and off at Station A and C, heading away from station B, only include Station B in the entity.

Here are some scenarios that describe which entity to select:

Scenario	Entity to include in the selector	Where alert will be visible
Train route won’t serve Central Station	Route A’s route_id and Central Stations stop_id	On all Route A trips travelling towards Central Station
Central Station is closed	Only Central Station’s stop_id	On all routes that serve Central Station
Route B is significantly delayed along the whole route	Only Route B’s route_id	On Route B, in both directions

Effect

The Effect field specifies how service is disrupted. Using the most appropriate effect in an alert allows riders and trip planners to correctly understand the severity of and adapt to the service disruption. There are nine possible values to choose from. Transit assigns each Effect to a predetermined severity level that specifies its impact in the app. The chosen effect will be used to generate copy visible in the app (below departures, for example).

Severity levels

Transit categorizes alerts into one of three levels: Severe, Warning, or Info. Each severity level displays differently and has different impacts on functionality in the app.

Consult the table below for a breakdown of each severity level. For examples of how each severity level displays in Transit, consult the Alert behavior / How alerts are displayed section below.

Note: Transit does not consume experimental severity levels. We will only infer severity from effect/entity combinations.

Transit effect detection

If the service alert is set to “Other Effect” and “Unknown Effect”, Transit will do a simple, automated analysis of the text to determine a more specific effect. For example, if it says “Detour on Route 100,” we’ll infer that a more appropriate effect is Detour.

⚠️ Please note: It is preferable to specify the appropriate alert level (see above table) rather than using “Other Effect” or “Unknown Effect.” If your use of Other or Unknown effects is deliberate, please let us know so we can disable this behaviour.

Header and description

The alert text should provide more context and concisely explain how to plan around the service disruption. For example, if a stop moved, it’s important to tell the rider where it went. If a line is detoured, include a description of the temporary deviated route. The text can also add more details on the cause of the disruption.

Best practices:

Use line breaks to make your service alert easier to read.
While there is no character limit for service alerts, users will be viewing alerts on mobile devices. Please be as concise as possible without sacrificing clarity. As a rule of thumb: header_text should fit in a push notification, and descriptions should fit on a screen (150-200 words).
If the affected entity is a trip_id, include the departure time and headsign in the alert description copy
Service alerts should contain information about transit service specific to the affected line, stop, or trip only. Please don’t use them to advertise unrelated events or promote other apps.
If the Header Text is not provided, Transit may use the CAUSE field to generate a header. The cause field does not impact routing.

Translations

The header and description text may be localized using the Translation message to the eight languages that Transit supports. Users will see the copy in their device language when it is available. If not, they will see the alert in the agency’s default language.

Make sure languages are labelled correctly, so users receive alerts in their app’s language as often as possible.

Time ranges:

The TimeRange field specifies when the service alert applies and tells riders when to expect changes to their transit service. Active alerts are displayed most prominently in the app. Future alerts are displayed less prominently than active alerts but are considered when riders plan trips during the affected time. Transit can display alerts up to two weeks in advance of when they take effect.

If no time ranges are specified in the data, Transit considers the alert to be active for as long as it is in the feed.
If an alert has repeating time ranges covering multiple days, it should specify a time range for each day covered. For example, an alert with a week-long nightly closure would include seven time ranges.
When possible, include future alerts, so riders can prepare for service changes.
Push notifications [link to push notification section] will be sent when the disruption starts, not when the alert is published.
Only publish information you know to be certain – it’s better to not provide an end date than to include an incorrect one.

Unsupported fields

Transit does not currently support the following fields:

Clickable links in the copy
Formatting (bold, italics, etc.)
URL field

How alerts are displayed / Alert behavior

How service alerts in Transit are displayed is primarily a function of the alert severity. The higher the severity level, the more visible the alert is in the app.

Here’s a comprehensive breakdown.

Severe alerts

Severe alerts will send push notifications to users who have subscribed to receive notifications for the affected route. Push notifications can be enabled per-route, and will alert the user of the disruption even when the application is closed.

Example 1: Severe alert for an entire route

Transit will replace the upcoming departure with a hazard symbol (⚠️) if a “No service” alert is applied to a route. If a rider taps on the route, the alert will appear prominently in red and all departures will be crossed out.

Example 2: Severe alert on a stop

Transit displays severe alerts on stops slightly differently depending on how close a rider is to that stop. If a rider is within 500m of the closed stop, Transit will automatically reroute them to the nearest open stop and display “Nearest stop closed” in orange. A small ⚠️ symbol will appear next to the route name or number in Nearby.

A stop with a severe alert is will not be considered by the trip planner.

If a rider is more than 500m from the next open stop, Transit will display “No service at this top” in red if the user taps on the route. A small ⚠️ symbol will display next to the route name or number on the Nearby screen.

Example 3: Closed entrances

If a station entrance is marked as closed, Transit will display it in Route Details. This will not be visible in Nearby.

Example 4: Severe alert on trip

For a severe alert on a trip, Transit will display a “Cancelled” label next to a struck-through departure time. In Nearby, the cancelled departure will be skipped and Transit will display the upcoming unaffected departure.

Warning alerts

Warning level alerts display next to the route name or number on Nearby, and feature prominently in yellow when consulting upcoming departures in Route Details.

Example 1: Warning alert on an entire route

Warning alerts at the route level show a small ⚠️ icon next to the route name and an yellow card under upcoming departures.

Example 2: Warning alert on stop

Warning alerts for a specific stop will also appear in Nearby as a small ⚠️ icon next to the route name, but only for users for which that stop is closest. When consulting Route Details, the affected stop will be shown with a yellow circle, and a yellow card will appear under upcoming departures.

Example 3: Warning alert on trip

Warning alerts at the trip level also appear as a small ⚠️ icon next to the route name in Nearby. In Route Details, a small ⚠️ icon is also present at the bottom of the ETA card for the affected trip, in addition to a yellow card underneath the departures.

Info alerts

Info level alerts are visible only in Route Details when a rider consults upcoming departures. They are not visible in Nearby.

Note that they might appear after other information about the route, like fares or on time performance cards.

Upcoming alerts will appear as Info level alerts until they start, regardless of their severity level.