Guidelines¶

In this section, we suggest general practices regarding the use of the Service Alerts feed.

General Guidelines¶

It is possible to include multiple affected services (routes, stops, etc) per alert if the affected services are part of the same incident and under the same effect (e.g. the same NO_SERVICE alert for multiple routes closed due to the same event, or the same STOP_MOVED alert for multiple stops moved in bulk due to the same construction). This helps consolidate information for riders under the same alert.
Although communication_period, impact_period, cause and effect are not required fields, it is recommended to include these fields in all alerts to provide as much information about the alert as possible.
If more details exist, such as further information about the cause of the alert or the extent of the effect, it is possible to elaborate on them using cause_detail and effect_detail (Note: cause_detail and effect_detail are experimental fields).
If a web page with details of the alert exists, such as detailed graphics of detours, it can be included in the url field.
If a service disruption is known in advance, add it to the feed prior to its start time.
If an alert is still not in effect yet, consider adding a note in the header such as “Upcoming: “. Remember to update the header, so it is always accurate at the time a rider sees it.
Once the communication_period (or active_period) of the alert has passed, remove the alert from the feed. It is possible to have an alert with a NO_EFFECT effect that informs the rider that the incident ended. However, this is not necessary.

Prioritization of GTFS Schedule¶

If the service disruption is planned, try to incorporate the service change in the GTFS Schedule feed (eg: remove a closed stop from stop_times.txt for the corresponding trip until the stop is back in service). You can still use GTFS Realtime Service Alerts as a complement to notify users of upcoming disruptions or adjustments.
If the alert is the result of an unplanned short-term event (usually lasting less than one week), you do not need to make adjustments to the corresponding GTFS Schedule.
If the unplanned alert continues over a longer period of time, continue using GTFS Realtime Service Alerts and consider incorporating the service change in the GTFS Schedule feed if the event is expected to last over one month.

For more detailed information regarding the tradeoff between GTFS Schedule and GTFS-RT, visit the Realtime vs Schedule Best Practices document.

Cause & Effect¶

cause and effect should not be empty, even if that information is included in the header or description of the alert.
When possible, include a specific effect. Try to minimize the number of unknown or generic effects (UNKNOWN_EFFECT, OTHER_EFFECT). This allows trip planners to extract the nature of the service disruption without having to analyze the header or description.

Communication Period and Impact Period (previously Active Period)¶

Note

The field active_period was used to specify the time periods covered by the alert. However, it was deprecated in PR#546 to resolve the ambiguity around its use. You could still use active_period for backward compatibility reasons.

We recommend the usage of communication_period and impact_period. Please refer to the migration guide here to ensure a smooth transition.

Guidelines specific to communication_period and impact_period:

The communication period is the time when the alert should be shown to the user strictly for informative reasons.
The impact period is the time when the services are actually affected by the alert on the ground.
Always ensure that each impact period is contained within at least one communication period to ensure that the alert is communicated to riders during any time the service disruption is in effect.

General time period guidelines:

If the end time of the alert is known, include it in the impact period/active period. Otherwise, leave the end time empty and make sure to include it once it is known.
If the alert is recurrent, create multiple time intervals. If using communication_period and impact_period, you could keep a single continuous communication period and multiple time intervals in the impact period. This is done to keep the information available for riders even when the disruption is not happening.

Informed Entity¶

Tip

To supplement this theoretical section with practical examples, please consult informed entities in the next section, Real-life Use Cases.

If an incident occurs, first consider setting an alert with the most granular entity possible, and then assess whether additional alerts at higher level entities are necessary.

Example: A station serving multiple metro routes is closed for one metro route only due to maintenance. Only the platforms serving that specific route are closed.
- Start by creating a NO_SERVICE alert where the informed_entity includes the stop_id for the metro’s platform, as well as the route_id of the metro.
- Then you might be able to create additional alerts with other effects. E.g. For the same example above, you can create an additional MODIFIED_SERVICE or OTHER_EFFECT alert that informs the riders about the maintenance, and includes the station’s stop_id in informed_entity.
If you do not specify the most granular entity, be careful with the effect of the alert and do not set it to NO_SERVICE. This is because many consumers might actually use the NO_SERVICE alert to not suggest the affected services, which will lead to incorrect journey suggestions for users.

Example: A stop serving multiple routes is skipped by only one of the routes. If you only specify the stop_id in informed_entity without including route_id, then do not set NO_SERVICE as the effect. This is because certain consumers might decide to close the stop for all routes based on the information provided in informed_entity. You can set an effect such as MODIFIED_SERVICE.
Make sure the informed entities are as granular as possible
- If the alert is for the whole agency, include agency_id.
- If the alert is for certain routes, include route_id.
- If the alert is along certain directions, include direction_id.
- If the alert is for certain stops, include stop_id.
- If the alert is along certain directions, and the stop it affects serves multiple directions in the GTFS, include both stop_id and direction_id.
- If the alert is for certain trips, include trip_id using TripDescriptor.

Info

Currently, direction_id is still an experimental field.

Do not include route_ids for routes whose service period starts after the alert’s impact_period/active_period or ends before the alert’s impact_period/active_period.

A decision tree containing major use cases of Service Alerts and the corresponding informed_entity is represented in the following board

[MobilityData][Public] Decision tree for informed_entities

Info

Informed Entity could be expanded in the future to allow for the inclusion of other entities such as pathway_id. This expansion is subject to ongoing community discussions mainly in the transit repo, or from conversations that start in working groups and lead to proposals in the transit repo.

Header Text¶

Keep the header as short as possible, while conveying the message.
Mention the effect in the header in a straightforward way.
It is possible to add the time period and the cause of the alert in the header if they do not make the header too long.
Do not list multiple alerts in the header text.
While HTML and Markdown characters and tags are UTF-8, it is discouraged to use those characters in the header text, as the spec currently defines the header text as plain text.
Similarly, do not include language codes such as “en-html", since it is not BCP-47.
Examples of headers
- ✅ "Interrupted Service" ← Can be improved
- ✅ "Blue Line: No service between Snowdon and Acadie"
- ✅ "Orbit Earth Detour between Rio Salado Pkwy./Packard Dr. and Tempe Transportation Center - Reggae Festival"
- ❌ "No service for Subway Line A, buses running for Subway Line K" ← Multiple alerts

Description Text¶

Do not list multiple alerts in the same alert description.
While HTML and Markdown characters and tags are UTF-8, it is discouraged to use those characters in the description text, as the spec currently defines the description text as plain text.
Similarly, do not include language codes such as “en-html", since it is not BCP-47.
Keep the description short enough but as detailed as possible.

Good example (Halifax Transit)

"descriptionText": {
 "translation": [
   { 
     "text": "Stop Closure Notice:\r\nRoute: 4 Universities Inbound\r\nLocation: Robie St Before Cedar St (8196)\r\nCause:  Stop Closed Construction\r\n\r\nAffected Stops:\r\nRobie St Before Cedar St (8196)",
     "language": "en"
   }
 ] 
}

Bad example (MBTA): The alert mentions all needed information in the header and leaves only the direction for the description.

"headerText": {
 "translation": [
   { 
     "text": "Haverhill Line Train 1231 (10:25 am from North Station) is operating 10-20 minutes behind schedule between North Station and Reading due to a signal issue.",
     "language": "en"
   }
 ]
},
"descriptionText": {
 "translation": [
   {
     "text": "Affected direction: Outbound",
     "language": "en"
   }
 ]
}

URL¶

Make sure the URL directs to a page that details the alert or contains information directly related to it. For example, the URL directs to a page containing illustrations of a detour or a moved stop.
Avoid generic URLs or URLs that direct to pages where the user has to navigate further to find details about the alert.

Image (Experimental)¶

The image field contains a URL that links to an image that further details the alert. Examples include: Shape of a detour along a map, new location of a moved stop, etc.
The image must not contain too much text.
The image should not contain new textual information that is not mentioned in the alert header or description.

Handling suspicious and ambiguous alerts¶

Some alerts are ambiguous or incomplete. Examples of these alerts include:

An alert with no impact_period/ active_period to indicate the service disruption's start time and/or foreseeable end time.
A NO_SERVICE alert with the no informed entity or with the whole agency_id as an informed entity.
A NO_SERVICE alert describing a segment closure but the informed entities include only the route_id.
A NO_SERVICE alert describing a platform closure but the stop_id for the entire station is provided.
A NO_SERVICE alert describing some cancelled trips but the informed entities contain the route_id only.
A DETOUR alert with changed stop locations and whose informed entities contain only the route_id.

Such cases indicate incomplete information which hinder the consumer’s interpretation of the data.

Producers are encouraged to refrain from practices that lead to incomplete or ambiguous interpretations and to include informed entities and active periods that are as granular as possible.
If a producer does not include the most granular informed entities in an alert, they are encouraged to not use NO_SERVICE as an effect. This is because some consumers decide to use alerts with NO_SERVICE to affect their routing suggestions. This practice, coupled with non-detailed informed entities, can result in false service closures.
Consumers are encouraged to be very careful if they decide to use Service Alerts to impact journey planning. If a consumer uses alerts to affect their routing, they should monitor the alerts’ descriptions and contact the agency if an alert contains incomplete information.
If a consumer chooses to use Service Alerts to affect routing, using alert effects other than NO_SERVICE to affect routing is strongly discouraged, as it carries significant risk and can lead to unintended consequences.
Producers are encouraged to implement TripModifications and include all detours there.