Providing a comprehensive service alerts feed empowers riders to adapt to incidents that might affect their trip. 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.
- Effect: Why service is disrupted
- Entity selectors: What services are affected
- Time ranges: When the service alert applies
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 firstname.lastname@example.org for help.
The GTFS-RT Service Alerts Feed
In order to display relevant alerts to riders, we need to know the most important details of the alert, including why service is disrupted, when the service alert applies, and what transit services are affected.
Effect: Why 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.
|Effect||App severity level||Notes|
|No Service||Severe (Will send push notification)||Will close all selected entities on the home screen and in the trip planner.|
|Reduced Service||Warning (Will send push notification)|
|Detour||Warning (Will send push notification)|
|Other Effect||Info||Transit may analyze the text of the alert to provide a more specific effect.|
|Stop Moved||Info or Warning (Will send push notification)||Warning when alert contains a stop ID, info if only at the route level.|
|Accessibility||Warning for users with step-free settings, hidden for others||Accessibility alerts affect the trip planner for, and are only visible to, users who have step-free access enabled.|
- If you select "No Service" for a stop, Transit will hide the stop. It will not be considered by the trip planner, and the list of nearby transit options will show the next closest stop. If you use this option, ensure you have selected the correct stop.
- Avoid using "Other Effect" and "Unknown Effect", if possible.
- Service alerts should contain information about transit service specific to the affected line or stop only. Please don’t use them to advertise unrelated events or promote other apps.
Entity selectors: What services are affected
Entity selectors specify what stops or routes are 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.
Central Station is served by bus routes A and B.
|Scenario||What to include in the selector||Who will see the alert|
|Route A won’t serve Central Station||Route A’s ID, and Central Station’s ID||Riders on Route A travelling towards Central Station|
|Central Station is closed||Only Central Station’s ID||Riders on both routes travelling towards Town Hall.|
|Route B is significantly delayed along the whole route||Only Route B’s ID||Riders on Route B, in both directions.|
Transit currently supports route and stop entity selectors best. Alerts affecting an entire agency are interpreted to affect every route that an agency operates. Alerts that apply to a specific trip are applied to that trip’s route, but “no service” (i.e. a cancelled trip) is changed to “reduced service” in the app.
- All identifiers must match the static data (GTFS)
- If an alert affects all stops on a route, do not specify entity selectors for every stop. Specify only one, which includes the route ID.
- Choose the most specific entity possible; we support entrances, platforms, and boarding areas.
How it's displayed
Time ranges: When the service alert applies
The TimeRange field 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.
- Only publish information you know to be certain – it’s better to not provide an end date than to include an incorrect one.
How it’s displayed
The alert copy should 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.
- Clickable links and formatting (bold, italics, etc.) are not supported.
- 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.
- Make sure languages are labelled correctly so users receive alerts in their app’s language as often as possible.