Alerts
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.
The GTFS-RT Service Alerts Feed
- Effect: Why service is disrupted
- Entity selectors: What services are affected
- Time ranges: When the service alert applies
Copy
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.
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: 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. 
| 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. Trip cancellations will also appear with a strike-through in the list of departures. |
| Reduced Service | Warning (Will send push notification) | |
| Detour | Warning (Will send push notification) | |
| Additional Service | Info | |
| Modified Service | Info | |
| Other Effect | Info | Transit may analyze the text of the alert to provide a more specific effect. |
| Unknown Effect | Info | |
| 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. |
| No Effect | Not displayed |
Best practices
- 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, stop, or trip 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.
Example
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 Central Station |
| 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, stop and trip entity selectors best. Alerts affecting an entire agency are interpreted to affect every route that an agency operates.
Trip alerts
The latest versions of Transit (5.15.7+) include improved support for trip entity selectors. An alert with a "No service" effect and a trip selector will appear with the red warning sign next to the cancelled departure time. Similar to route selectors, you may also include one or multiple stop IDs, if the alert only affects specific stops on the defined trip. For example: if the 8:15AM departure will be boarding from a different platform, that alert would appear on departures for that stop only.
All trip alerts will also be visible in the alerts view, so be sure to specify the departure time and headsign in the copy so riders can correctly identify the impacted trips.
Best practices
- 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. Similarly, do not specify every trip ID if the alert affects all trips in the time range.
- Choose the most specific entity possible; we support entrances, platforms, and boarding areas.
- Include the departure time and headsign in the alert description copy when the alert affects a specific departure.
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.
Best practices
- 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
Copy
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.
Best practices
- 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.