Alerts guidelines

The following are the main goals of an Alert using General Transit Feed Specification (GTFS) Realtime (RT) feeds: 

• Communicate changes, cancellations, and service reductions or alterations.
• Add information to Transit events, and when possible, provide alternatives. 

This article gives you guidelines on how to create and manage alerts using GTFS-RT feeds.

These guidelines are subject to frequent changes. We suggest you regularly check the GTFS documentation and specification, join GTFS discussion groups, and keep an eye out for unexpected alert behavior. If you need further information, please contact us.

Before you begin

The following links are helpful introductions and guides to GTFS-RT and Alerts: 

• GTFS-RT overview
• Alerts references
• Guidelines to format text 

Alert guidelines

The following are some critical notes about alerts, and how we assess their quality:

• Be more generic than restrictive. Alerts can be bound to different entities on a feed. Alerts can point to an arbitrary combination of stops, stations, agencies, routes, and more at the same time. However, if you specify too many parameters, you might cancel out your alert. If your alert cancels out, your alert is accepted, but never displays. Example: If you define an alert for an agency and a route, but that route isn’t served by that agency, both conditions are never true, and your alert never displays. 
• Specify your time properly. Make sure your implementation doesn’t send past dates. The Alert message is received by our system and rejected, but you do not receive an instant warning or error code, so this is easy to miss. Always consult your Partner Front-End Validation Reports.
• Use the full range of CAUSE and EFFECT. The most important piece of information in an alert is the EFFECT. It indicates severity, and determines whether there are cancellations users should be alerted about. Depending on the severity, effects fall under one of the 3 alert levels. The table below demonstrates the alert severity and example alerts based on the alert effect. Icons and text aren’t guaranteed to display as desired.

Note: EFFECT = NO_SERVICE is an effect handled in a special way. Whenever an alert's effect is suspended services, we try to offer alternative routes to navigate users away from these stops or trips. By offering alternative routes, we enhance the user experience.

 

Alert level	Effect	Example
CRITICAL	NO_SERVICE SIGNIFICANT DELAYS	Significant delays
WARNING	REDUCED_SERVICE DETOUR MODIFIED_SERVICE STOP_MOVED	Reduced service  Modified service
INFORMATION	ADDITIONAL_SERVICE OTHER_EFFECT UNKNOWN_EFFECT	Information

 

• Ensure that you correctly specify languages. Correctly specifying languages provides a better experience for your users. If your original alert is in Russian, make sure you declare [ru] as the language. If you provide an English translation, declare it as [en]. Encode languages in UTF-8. HTML tags aren’t accepted.
• Optimize your URLs. Your URLs must take users straight to transit-related information, and not mislead users about what is on the page. There are 2 ways you can optimize your URLs:   
  • Do not let URLs take users to a generic or ad-rich page. Our users consider generic pages, or ad-rich pages as SPAM. Because of this perception, we consider this as a blocking issue. 
  • Publish the original URL. If there’s only one language for the URL, publish the original address only to indicate the correct language. Example: The URL is in German only, but it’s also published with an English translation pointing to the same URL.