diff --git a/config/en/mkdocs.yml b/config/en/mkdocs.yml index 280db7e7..7efd0b03 100644 --- a/config/en/mkdocs.yml +++ b/config/en/mkdocs.yml @@ -262,6 +262,11 @@ nav: - MobilityData Recommendations: - Overview: resources/mobilitydata-recommendations/overview.md - GTFS Schedule vs GTFS Realtime: resources/mobilitydata-recommendations/gtfs-schedule-vs-gtfs-realtime.md + - GTFS Realtime Service Alerts: + - Introduction: resources/mobilitydata-recommendations/gtfs-realtime-service-alerts/intro.md + - Guidelines: resources/mobilitydata-recommendations/gtfs-realtime-service-alerts/guidelines.md + - Real-world Use Cases: resources/mobilitydata-recommendations/gtfs-realtime-service-alerts/real-world-use-cases.md + - Real-life Examples: resources/mobilitydata-recommendations/gtfs-realtime-service-alerts/real-life-examples.md - Producing Data: resources/producing-data.md - Sharing Data: resources/sharing-data.md - Using Data: resources/using-data.md diff --git a/docs/en/assets/rt_alerts_guide_citymapper_screenshot.png b/docs/en/assets/rt_alerts_guide_citymapper_screenshot.png new file mode 100644 index 00000000..957d91aa Binary files /dev/null and b/docs/en/assets/rt_alerts_guide_citymapper_screenshot.png differ diff --git a/docs/en/assets/rt_alerts_guide_citymapper_screenshot_2.png b/docs/en/assets/rt_alerts_guide_citymapper_screenshot_2.png new file mode 100644 index 00000000..c0abf774 Binary files /dev/null and b/docs/en/assets/rt_alerts_guide_citymapper_screenshot_2.png differ diff --git a/docs/en/assets/rt_alerts_guide_transit_screenshot.png b/docs/en/assets/rt_alerts_guide_transit_screenshot.png new file mode 100644 index 00000000..3a62ea3e Binary files /dev/null and b/docs/en/assets/rt_alerts_guide_transit_screenshot.png differ diff --git a/docs/en/resources/mobilitydata-recommendations/gtfs-realtime-service-alerts/guidelines.md b/docs/en/resources/mobilitydata-recommendations/gtfs-realtime-service-alerts/guidelines.md new file mode 100644 index 00000000..384aeedf --- /dev/null +++ b/docs/en/resources/mobilitydata-recommendations/gtfs-realtime-service-alerts/guidelines.md @@ -0,0 +1,164 @@ +# 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. e.g. Add *“Upcoming: “* to the header. 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. This is not necessary. + +## 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 + + Prior to `communication_period` and `impact_period`, time periods for alerts were described using `active_period`, which was deprecated in [PR\#546](https://github.com/google/transit/pull/546) to resolve the uncertainty around its use. + Producers can still create `active_period` and consumers can still use it with the same general guidelines mentioned below for `communication_period` and `impact_period`. However, it is recommended to use `communication_period` and `impact_period` to make sure that the display time of the alert is distinct from when it comes into effect. + A migration guide from `active_period` to `communication_period` and `impact_period` can be found in the spec examples [here](https://github.com/google/transit/blob/master/gtfs-realtime/spec/en/examples/migration-active-period.md). + +* 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. +* If the end time of the alert is known, include it in the impact period and . 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. +* Always make sure that each impact period is contained within at least one communication period to make sure that the alert is communicated to riders during any time the service disruption is in effect. + +## Informed_entity + +* 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. + * e.g. 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.** + * e.g. 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](https://gtfs.org/documentation/realtime/reference/#message-tripdescriptor). + +!!! Note + + 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 + +!!! Note + + Informed Entity can 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](https://github.com/google/transit), or from conversations that start in [working groups](https://community.mobilitydata.org/working-groups#events) 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. E.g. 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. + +## Prioritization against GTFS Schedule + +* If the service disruption is planned, try to incorporate the service change in the [GTFS Schedule feed](https://gtfs.org/documentation/schedule/reference/) (eg: remove a closed stop from [`stop_times.txt`](https://gtfs.org/documentation/schedule/reference/#stop_timestxt) 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](../../../resources/mobilitydata-recommendations/gtfs-schedule-vs-gtfs-realtime.md)**. + +## Handling suspicious and ambiguous alerts + +Some alerts are ambiguous or incomplete, examples of these alerts include: + +* An alert with no `impact_period`/ `active_period` when the service disruption has a start time and/or a 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](https://gtfs.org/documentation/realtime/feed-entities/trip-modifications/) and include all detours there. \ No newline at end of file diff --git a/docs/en/resources/mobilitydata-recommendations/gtfs-realtime-service-alerts/intro.md b/docs/en/resources/mobilitydata-recommendations/gtfs-realtime-service-alerts/intro.md new file mode 100644 index 00000000..f2338daf --- /dev/null +++ b/docs/en/resources/mobilitydata-recommendations/gtfs-realtime-service-alerts/intro.md @@ -0,0 +1,44 @@ +# GTFS-Realtime Service Alerts Guidance: Introduction + +[GTFS-Realtime Service Alerts](https://gtfs.org/documentation/realtime/reference/#message-alert) allow their producer to provide updates whenever there is disruption on the network. Service Alerts can be used to express multiple types of service disruptions, incidents and information, including: + +* Closed routes and route segments. +* Closed stops and stations. +* Detours. +* Severe delays in service. +* Accessibility issues (eg: elevator not working). +* General announcements about service. + +Service Alerts can be used by multiple consumers: + +* Trip planner apps (e.g. Google Maps, Transit, Apple Maps, Citymapper, Moovit). +* Transit information websites +* Digital signage (bus stops, displays, etc.) +* Information channels (email, SMS, etc.) + +Service Alerts are used to communicate to riders that real-time incidents and disruptions are happening in a transit system either currently or in the future. Trip planners can also choose to not suggest the disrupted services based on the Alert. + +The screenshots below show possible trip planner behaviours based on GTFS-RT Service Alerts. In practice, alerts are used by trip planners : + +* Inform riders about service changes and disruptions. +* Influence journey suggestions to remove irrelevant and disrupted routes and stops. + +

+ + + +

+

Screenshots from TransitApp (left) and Citymapper (middle and right), employing Service Alerts.

+ +For more information, please refer to: + +* [The GTFS-Realtime Service Alerts reference page](https://gtfs.org/documentation/realtime/reference/). +* [The Service Alerts entity page](https://gtfs.org/documentation/realtime/feed-entities/service-alerts/). + +To validate your GTFS-Realtime Service Alerts feed, please refer to the [GTFS Realtime Validator](https://github.com/MobilityData/gtfs-realtime-validator). + +This document details some recommendations on how to use Service Alerts to the best of their abilities to provide alerts. + +1) We will attach each possible use case to its appropriate service alert setup. +2) We will explore the potential good and bad uses of certain fields. +3) We will go through some real life examples of Service Alerts, will evaluate them, and will suggest improvements to them. diff --git a/docs/en/resources/mobilitydata-recommendations/gtfs-realtime-service-alerts/real-life-examples.md b/docs/en/resources/mobilitydata-recommendations/gtfs-realtime-service-alerts/real-life-examples.md new file mode 100644 index 00000000..474061f1 --- /dev/null +++ b/docs/en/resources/mobilitydata-recommendations/gtfs-realtime-service-alerts/real-life-examples.md @@ -0,0 +1,736 @@ +# Real-life examples and how to fix them + +In this example, we present examples of Service Alerts that were created for real-world agencies. We explore the issues with these alerts and suggest improvements to them. + +## 1\) Toronto Transit Commission + +Published on 28-03-2025 + +* The header is badly formatted. It seems to continue into the description. +* The header should be modified to “Line 1 Yonge-University: No service between St George and St Andrew”. +* The description should be finished: “Service will resume…” +* The effect should be modified to `MODIFIED_SERVICE`. + * Do not set `NO_SERVICE` as this effect is currently generally concerned with stop and platform closures. In this case, it seems like the trip is effectively split in the middle into two separate trips. +* The cause should be modified to `MAINTENANCE`. +* Too many `route_ids` included as informed entities. The only route that should be mentioned is the Yonge-University Line (`route_id=1`). And all station stop_ids between St George and St Andrew should be mentioned. +* No time period is associated with the alert. + +``` +{ + "id": "1", + "alert": { + "informedEntity": [ + { + "agencyId": "1", + "routeId": "508" + }, + { + "agencyId": "1", + "routeId": "13" + }, + { + "agencyId": "1", + "routeId": "503" + }, + { + "agencyId": "1", + "routeId": "504" + }, + { + "agencyId": "1", + "routeId": "505" + }, + { + "agencyId": "1", + "routeId": "501" + }, + { + "agencyId": "1", + "routeId": "94" + }, + { + "agencyId": "1", + "routeId": "97" + }, + { + "agencyId": "1", + "routeId": "304" + }, + { + "agencyId": "1", + "routeId": "19" + }, + { + "agencyId": "1", + "routeId": "26" + }, + { + "agencyId": "1", + "routeId": "300" + }, + { + "agencyId": "1", + "routeId": "301" + }, + { + "agencyId": "1", + "routeId": "303" + }, + { + "agencyId": "1", + "routeId": "305" + } + `], + "cause": "UNKNOWN_CAUSE", + "effect": "UNKNOWN_EFFECT", + "headerText": { + "translation": [ + { + "text": "Line 1 Yonge-University: There i", + "language": "en" + } + ] + }, + "descriptionText": { + "translation": [ + { + "text": "There is no subway service on Line 1 Yonge-University between St George and St Andrew stations due to planned track work. Shuttle buses will not operate. Follow the station signs or speak to a TTC employee for help. Service will resume", + "language": "en" + } + ] + } + } +} +``` + +**Improved alert** + +``` +{ + "id": "1", + "alert": { + "informedEntity": [ +{ + "agencyId": "1", + "routeId": "1", + "stopId": "14445", // St George Station - southbound platform` +}, +{ + "agencyId": "1", + "routeId": "1", + "stopId": "14446", // Museum Station - southbound platform` +}, +`…` + +{ + "agencyId": "1", + "routeId": "1", + "stopId": "14421", // St Andrew Station - southbound platform` +}, +{ + "agencyId": "1", + "routeId": "1", + "stopId": "14422", // Osgoode Station - southbound platform` +}, +`...` + `], + "cause": "MAINTENANCE", + "effect": "NO_SERVICE", + "activePeriod": [ + { + "start": ...` + "end": ...` + } +`], + + "headerText": { + "translation": [ + { + "text": "Line 1 Yonge-University: No service between St George and St Andrew", + "language": "en" + } + ] + }, + "descriptionText": { + "translation": [ + { + "text": "There is no subway service on Line 1 Yonge-University between St George and St Andrew stations due to planned track work. Shuttle buses will not operate. Follow the station signs or speak to a TTC employee for help. Service will resume at 3AM.", + "language": "en" + } + ] + } + } + } +``` + +## 2\) BC Transit + +Published on 28-03-2025 + +* The header should be expanded: “No service in the Cowichan Valley due to Labour action.” +* The cause should be modified to `STRIKE`. +* The effect should be modified to `NO_SERVICE`. +* The URL mentioned in the description should be included in the `url` field. + +``` +{ + "id": "ft-TX1173397", + "alert": { + "activePeriod": [ + { + "start": "1739001600" + } + `], + "informedEntity": [ + { + "routeId": "2-COW" + }, + { + "routeId": "3-COW" + }, + `...` + + `], + "cause": "UNKNOWN_CAUSE", + "effect": "OTHER_EFFECT", + "headerText": { + "translation": [ + { + "text": "No Service" + } + ] + }, + "descriptionText": { + "translation": [ + { + "text": "Please be advised that all services in the Cowichan Valley are suspended due to labour action.\r\n\r\nWe apologize for any inconvenience this may cause. \r\n\r\nFor updates please sign up for alerts, please visit\u202fhttps://www.bctransit.com/cowichan-valley " + } + ] + } + } +} +``` + +**Improved alert** + +``` +{ + "id": "ft-TX1173397", + "alert": { + "activePeriod": [ + { + "start": "1739001600" + } + `], + "informedEntity": [ + { + "routeId": "2-COW" + }, + { + "routeId": "3-COW" + }, + `...` + + `], + "cause": "STRIKE", + "effect": "NO_SERVICE", + "headerText": { + "translation": [ + { + "text": "No service in the Cowichan Valley due to Labour action" + } + ] + }, + "descriptionText": { + "translation": [ + { + "text": "Please be advised that all services in the Cowichan Valley are suspended due to labour action.\r\n\r\nWe apologize for any inconvenience this may cause. \r\n\r\nFor updates please sign up for alerts, please visit\u202fhttps://www.bctransit.com/cowichan-valley" + } + ] + }, + `“url”: “https://www.bctransit.com/cowichan-valley”, + } +} +``` + +## 3\) MBTA + +Published on 02-04-2025 + +* Really good `informed_entity`, including the exact trip and direction. +* The header contains information that can be transferred to the description. +* The alert could use a `SIGNIFICANT_DELAYS` effect. + +``` +{ + "id": "634445", + "alert": { + "activePeriod": [ + { + "start": "1743086220", + "end": "1743091200" + } + `], + "informedEntity": [ + { + "agencyId": "1", + "routeId": "CR-Haverhill", + "routeType": 2, + "trip": { + "tripId": "SPRING2025V2-728425-1231-HaverhillBradfordVan", + "routeId": "CR-Haverhill", + "directionId": 0` + } + } + `], + "cause": "UNKNOWN_CAUSE", + "effect": "OTHER_EFFECT", + "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" + } + ] + }, + "severityLevel": "WARNING" + } +} +``` + +**Improved alert** + +``` +{ + "id": "634445", + "alert": { + "activePeriod": [ + { + "start": "1743086220", + "end": "1743091200" + } + `], + "informedEntity": [ + { + "agencyId": "1", + "routeId": "CR-Haverhill", + "routeType": 2, + "trip": { + "tripId": "SPRING2025V2-728425-1231-HaverhillBradfordVan", + "routeId": "CR-Haverhill", + "directionId": 0` + } + } + `], + "cause": "UNKNOWN_CAUSE", + "effect": "SIGNIFICANT_DELAYS", + "headerText": { + "translation": [ + { + "text": "Haverhill Line Train 1231 running behind schedule.", + "language": "en" + } + ] + }, + "descriptionText": { + "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. Affected direction: Outbound", + "language": "en" + } + ] + }, + "severityLevel": "WARNING" + } +} +``` + +## 4\) AMB-Mobilitat + +Published on 28-03-2025 + +* The affected stops (if known) should be added to both the description and to informed entities. +* Characters like \  and \\n should be replaced by plain text counterparts. + +``` +{ + "id": "24950", + "alert": { + "activePeriod": [ + { + "start": "1743724800", + "end": "1743811140" + } + `], + "informedEntity": [ + { + "routeId": "302" + }, + { + "routeId": "303" + }, + { + "stopId": "107046" + } + `], + "cause": "MAINTENANCE", + "effect": "DETOUR", + "url": { + "translation": [ + { + "text": "http://www.ambmobilitat.cat/Principales/Noticia.aspx?incidencia=24950&idioma=1", + "language": "ca" + }, + { + "text": "http://www.ambmobilitat.cat/Principales/Noticia.aspx?incidencia=24950&idioma=2", + "language": "es" + } + ] + }, + "headerText": { + "translation": [ + { + "text": "Desviament provisional al carrer Prat de la Riba afectant parades", + "language": "ca" + }, + { + "text": "Desv\u00edo provisional en la calle Prat de la Riba afectando paradas", + "language": "es" + } + ] + }, + "descriptionText": { + "translation": [ + { + "text": "Divendres 4 d’abril de 2025 durant tot el servei, es modifica el recorregut habitual al carrer Prat de la Riba de Santa Coloma de Gramenet amb l’anul·lació provisional de les parades afectades.\n\nLes línies seran desviades tal i com s’indica al plànol següent:\n\n\n", + "language": "ca" + }, + { + "text": "Viernes 4 de abril de 2025 durante todo el servicio, se modifica el recorrido habitual en la calle Prat de la Riba de Santa Coloma de Gramenet con la anulación provisional de las paradas afectadas.\n\nLas lineas serán desviadas tal y como se indica en el siguiente plano:\n\n:\n", + "language": "es" + } + ] + } + } +} +``` + +## 5\) King County Metro + +Published on 28-03-2025 + +* The cause should be modified to `OTHER_CAUSE`. +* A description should be added. + +``` +{ + "id": "18180", + "alert": { + "activePeriod": [ + { + "start": "1657226640" + } + `], + "informedEntity": [ + { + "agencyId": "1", + "routeId": "102698", + "routeType": 3` + } + `], + "cause": "UNKNOWN_CAUSE", + "effect": "NO_SERVICE", + "url": { + "translation": [ + { + "text": "https://svtbus.org/duvall-monroe-shuttle/", + "language": "en" + } + ] + }, + "headerText": { + "translation": [ + { + "text": "Duvall-Monroe Shuttle service is suspended until further notice due to driver shortage.\n\n", + "language": "en" + } + ] + }, + "descriptionText": { + "translation": [ + { + "text": "", + "language": "en" + } + ] + }, + "severityLevel": "SEVERE" + } +} +``` + +## 6\) Ruter \- OSLO + +Published on 02-04-2025 + +* No cause or effect are mentioned. At least a `MODIFIED_SERVICE` effect should be added. + * Do not set `NO_SERVICE` as this effect is currently generally concerned with stop and platform closures. In this case, it seems like the trip is effectively split in the middle into two separate trips. +* The `route_id` for the metro should be included in `informed_entity`, along with the unserved segment of stations. +* If the replacement bus service does not exist in the GTFS Schedule, it should be added to the GTFS Schedule. If the replacement bus service corresponds to a route in the GTFS and you cannot define the additional trips in the GTFS Schedule, then create it in `tripUpdates` with the `TripDescriptor \= NEW`. +* The language codes need to be provided with the header and description text. + +``` +{ + "id": "RUT:SituationNumber:732042", + "alert": { + "activePeriod": [ + { + "start": "1743130800", + "end": "1762218000" + } + `], + "url": {}, + "headerText": { + "translation": [ + { + "text": "Buss for T-bane mellom Borgen og Majorstuen" + }, + { + "text": "Bus replacement service between Borgen and Majorstuen " + } + ] + }, + "descriptionText": { + "translation": [ + { + "text": "Buss erstatter T-banen mellom Borgen og Majorstuen. T-banen kj\u00f8rer Kols\u00e5s\u2013Borgen og Stortinget\u2013Mortensrud." + }, + { + "text": "Bus replaces the Metro between Borgen and Majorstuen. The Metro runs between Kols\u00e5s and Borgen, and between Stortinget and Mortensrud." + } + ] + } + } +} +``` + +## 7\) Calgary Transit + +Published on 02-04-2025 + +* The field `agency_id` does not exist in the GTFS Schedule. So the agency_id in informed entities points to the agency_name. Since there is only one agency in the GTFS Schedule feed (Calgary Transit), it is better to only keep the `route_id` in `informed_entity`. +* A header should be added. +* The description text should become plain text. +* The description seems to include the cause and effect of the alert. + * The cause should be added as `WEATHER`. + * The effect mentioned is `SIGNIFICANT_DELAYS`. However, the description alludes to closed stops or potentially a detour. Therefore, the description should be clarified along with the effect. + * If possible, split the alert into multiple alerts; one for the stop closure or detour, the other for any significant delays that might arise from it. + +``` +{ + "id": "143607", + "alert": { + "activePeriod": [ + { + "start": "1743605700", + "end": "1743832740" + } + `], + "informedEntity": [ + { + "agencyId": "Calgary Transit", + "routeId": "123" + } + `], + "headerText": { + "translation": [ + { + "text": "", + "language": "en" + } + ] + }, + "descriptionText": { + "translation": [ + { + "text": "

Due to current weather conditions, we are unable to serve Hidden Creek Drive N.W.\n

Stops temporarily closed:\n

Northbound: #9340, #9341, #9342 and #9705\n

Buses running to North Point will travel:\n

\n

For more information on snow detours, please visit calgarytransit.com/snowdetours", + "language": "en" + } + ] + } + } +} +``` + +## 8\) MTA New York City Transit + +Published on 02-04-2025 + +* The header is much longer than the description. The second part of the header “ \- use the stops on Lexington Ave at E 53rd St or E 41st St instead” can be transferred to the description. +* The `stop_id` for Lexington Ave at E 46th St should be added to each entity in informed entities, to specify that the alert is only applied to the affected routes at the “Lexington Ave at E 46th St “ stop only. If the affected routes are the only routes that use that stop, then the `route_ids` are not necessary to include. +* The cause should be added as `CONSTRUCTION`. +* The effect should be added as `NO_SERVICE`. +* HTML entities like “\” should be replaced with plain text alternatives. +* The “en-html” translation should be removed. + +``` +{ + "id": "lmm:planned_work:21840", + "alert": { + "activePeriod": [ + { + "start": "1733288400", + "end": "1759104000" + } + `], + "informedEntity": [ + { + "agencyId": "MTA NYCT", + "routeId": "SIM11" + }, + { + "agencyId": "MTA NYCT", + "routeId": "SIM6" + } + `], + "headerText": { + "translation": [ + { + "text": "Southbound SIM6 and SIM11 buses are skipping the stop on Lexington Ave at E 46th St - use the stops on Lexington Ave at E 53rd St or E 41st St instead", + "language": "en" + }, + { + "text": "

Southbound SIM6 and SIM11 buses are skipping the stop on Lexington Ave at E 46th St - use the stops on Lexington Ave at E 53rd St or E 41st St instead

", + "language": "en-html" + } + ] + }, + "descriptionText": { + "translation": [ + { + "text": "See a map of the bypass.\n\nWhat's happening?\nWater main construction", + "language": "en" + }, + { + "text": "

See a map of the bypass.

What's happening?

Water main construction

", + "language": "en-html" + } + ] + } + } +} +``` + +## 9\) MTA Bus Company + +Published on 02-04-2025 + +* The effect should be modified to `ACCESSIBILITY_ISSUE`. +* The cause should be modified to `MAINTENANCE` or `CONSTRUCTION`. +* In `informed_entity`, the `stop_id` for the \[7\] platform should be mentioned, the station as well. +* “accessibility icon” should be removed, and HTML entities like “\ ” should be replaced with plain text alternatives. +* The “en-html” translation should be removed. + +``` +{ + "id": "lmm:planned_work:22052", + "alert": { + "activePeriod": [ + { + "start": "1734411600", + "end": "1758672000" + } + `], + "informedEntity": [ + { + "agencyId": "MTABC", + "routeId": "Q70+" + + } + `], + "headerText": { + "translation": [ + { + "text": "74 St-Broadway/Jackson Hts-Roosevelt Av [E][F][M][R][7] Station elevators from the street level to mezzanine and to/from the [7] platform are closed", + "language": "en" + }, + { + "text": "

74 St-Broadway/Jackson Hts-Roosevelt Av [E][F][M][R][7] Station elevators from the street level to mezzanine and to/from the [7] platform are closed

", + "language": "en-html" + } + ] + }, + "descriptionText": { + "translation": [ + { + "text": "accessibility icon The nearest accessible subway station connecting with the Q70-SBS is 61 St-Woodside accessibility icon [7]. \n\nFor additional travel alternatives, plan your trip at mta.info, use the MTA app (download the app for iOS or Android), or check our Elevator & Escalator Status page.\n\nWhat's happening?We're replacing the elevators", + "language": "en" + }, + { + "text": "

[accessibility icon] The nearest accessible subway station connecting with the Q70-SBS is 61 St-Woodside [accessibility icon] [7].

For additional travel alternatives, plan your trip at mta.info, use the MTA app (download the app for iOS or Android), or check our Elevator & Escalator Status page.

What's happening?
We're replacing the elevators

", + "language": "en-html" + } + ] + } + } +} +``` + +## 10\) BigBlueBus + +Published on 02-04-2025 + +* The alert includes the effect, cause, `informed_entity` and an open-ended `active_period`. +* The description is concise and shares the necessary information. +* The alert could also include route 7 in the header. It could also include route 7 in informed entities if the stop is skipped only by route 7\. +* The alternate stops should be listed in the alert description. +* The URL seems to be a link to the agency’s general alerts page, rather than specific information related to this alert. The URL needs to direct the rider to a page that details the alert or contains information directly related to it. + +``` +{ + "id": "3f0a0d8a-f751-4d79-843a-98227f597a7d", + "alert": { + "activePeriod": [ + { + "start": "1736185080" + } + `], + "informedEntity": [ + { + "stopId": "1717" + } + `], + "cause": "MAINTENANCE", + "effect": "NO_SERVICE", + "url": { + "translation": [ + { + "text": "https://www.bigbluebus.com/Newsroom/Content.aspx?type=Alerts" + } + ] + }, + "headerText": { + "translation": [ + { + "text": "Stop Closure on Pico Blvd. & Stanley Ave." + } + ] + }, + "descriptionText": { + "translation": [ + { + "text": "Route 7 bus stop located on WB Pico Blvd. at Stanley Ave. will be closed until further notice. For alternate stops, visit: bigbluebus.com/servicealerts." + } + ] + } + } +} +``` diff --git a/docs/en/resources/mobilitydata-recommendations/gtfs-realtime-service-alerts/real-world-use-cases.md b/docs/en/resources/mobilitydata-recommendations/gtfs-realtime-service-alerts/real-world-use-cases.md new file mode 100644 index 00000000..6b184a55 --- /dev/null +++ b/docs/en/resources/mobilitydata-recommendations/gtfs-realtime-service-alerts/real-world-use-cases.md @@ -0,0 +1,496 @@ +# Real-world use cases + +In this section, we explore all possible use cases of Service Alerts in real life. For each use case, we include the best alert practices. + +## Route Closure + +Example of service change: + +* Route is suspended for a certain period. + +Effect: + +* `NO_SERVICE` + +Informed Entity: + +* `route_id` +* `direction_id` (if the route is not running along a direction). + +Suggestions: + +* Add an alert that clearly mentions: + * That there is a route closure (in the header). + * The name of the affected route (in the header). + * Direction of the affected route if applicable (in the header). + * The time period(s) that the service disruption spans (in the description, can be also additionally included in the header if it doesn’t make the header overlong). + * If there is any replacement service, include the information (in the description). + +* If `tripUpdates` are provided, change `ScheduleRelationship` in the `TripDescriptor` of the affected trips to CANCELED if possible. +* If there is any replacement service and it is possible to create, then you can either: + * Create it in the GTFS Schedule feed if the closure is planned or once it extends over time and you have more certainty around the closure. + * If that replacement service corresponds to a route in the GTFS and you cannot define the additional trips in the GTFS Schedule feed, then create it in `tripUpdates` with the `TripDescriptor \= NEW`. + +!!! Note "Suggested template" + + Header: “ Service interrupted on route `{route name}`” + + Description: “Due to {cause}, service is suspended on route/line `{route name}` from`{start time}` to `{end time if applicable}`. Please use `{replacement suggestion}` instead.” + +--- + +## Trip Cancellation + +Example of service change: + +* Specific trips are cancelled. + +Effect: + +* `NO_SERVICE` + +Informed Entity: + +* `route_id` +* `direction_id` (if the route is not running along a direction). +* `trip_id` using TripDescriptor. + * If the trips are frequency-based, add `start_time` and `start_date` under TripDescriptor to match to a single trip. + +Suggestions: + +* Add an alert that clearly mentions: + * That there is a trip cancellation (in the header). + * The name of the affected route (in the header). + * Direction of the affected route if applicable (in the header). + * Human-readable identifier of the cancelled trips if possible, such as the start time (in the description). + * If there is any replacement service, include the information (in the description). + +* If `tripUpdates` are provided, change `ScheduleRelationship` in the `TripDescriptor` of the affected trips to CANCELED if possible. +* If there is any replacement service and it is possible to create, then you can either: + * Create it in the GTFS Schedule feed if the closure is planned or once it extends over time and you have more certainty around the closure. + * If that replacement service corresponds to a route in the GTFS and you cannot define the additional trips in the GTFS Schedule feed, then create it in `tripUpdates` with the `TripDescriptor \= NEW`. + +!!! Note "Suggested template" + + Header: “ Trips cancelled on route `{route name}`” + + Description: “Due to {cause}, a few trips are cancelled on `{direction}` route/line `{route name}`. The current trips are affected `{human-readable trip identifier, e.g. start time}`. Please use `{replacement suggestion}` instead.” + +--- + +## Route segment closure + +Example of service change: + +* The bus does not run between two stops. + +Effect: + +* `NO_SERVICE` +* You may also use `MODIFIED_SERVICE` when you expect consumers to use the alert to adjust journey suggestions or routing, and if you expect that setting an effect of `NO_SERVICE` could result in presenting inaccurate information to riders. + +Informed Entity: + +* `route_id` +* `direction_id` (if the route is not running along a direction). +* `stop_id` + * If the bus route is not running from `stop_A` to `stop_B`, include the`route_id`, `direction_id`, and all the `stop_ids` between `stop_A` and `stop_B` along the direction. + * Do not include the first and last stop of the segment in the informed entity if they are not affected by the disruption. Only include the stops of the segment that are actually closed. + +Suggestions: + +* Add an alert that clearly mentions: + * That there is a route segment closure (in the header). + * The name of the affected route (in the header). + * Direction (header) and the extremity stops of the affected segment (in the header and/or description). + * The time period(s) that the service disruption spans (in the description, can be also additionally included in the header if it doesn’t make the header overlong). + * If there is any replacement service, include the information (in the description). + +* If `tripUpdates` are provided, change `ScheduleRelationship` in the `StopTimeUpdate` of affected `stop_times` of each relevant trip to SKIPPED if possible. +* If there is any replacement service and it is possible to create, then you can either: + * Create it in the GTFS Schedule feed if the closure is planned or once it extends over time and you have more certainty around the closure. + * If that replacement service is operated by a pre-existing route and you cannot define it in the GTFS Schedule feed, then create it in `tripUpdates` with the `TripDescriptor \= NEW`. + +!!! Note "Suggested template" + + Header: “No route `{route name}` service between `{start stop}` and `{end stop}`” + + Description: “Due to {cause}, route/line `{route name}` does not serve the stops between `{start stop}` and `{end stop}`, from`{start time}` to `{end time if applicable}`. Please use `{replacement suggestion}` instead.” + +--- + +## Stop Closure + +Example of service change: + +* A stop is closed to pick-ups and drop-offs. +* The platform of a station is closed to pick-ups and drop-offs. + +Effect: + +* `NO_SERVICE` + +Informed Entity: + +* `stop_id` + +Suggestions: + +* Add an alert that clearly mentions: + * That there is a stop closure (in the header). + * The name of the affected stop or platform (in the header). + * The time period(s) that the service disruption spans (in the description, can be also additionally included in the header if it doesn’t make the header overlong). + +* If `tripUpdates` are provided, change ScheduleRelationship in the `StopTimeUpdate` of affected `stop_times` to SKIPPED if possible. +* Remove the `stop_id` from the stop time entries in `[stop_times.txt](https://gtfs.org/documentation/schedule/reference/#stop_timestxt)` for trips that serve the closed stop. This is more important if the alert extends over time (weeks to months). +* If it is certain that the stop is going to be permanently closed, remove it from the GTFS Schedule feed. Otherwise, you do not need to remove the stop from `[stops.txt](https://gtfs.org/documentation/schedule/reference/#stopstxt)`. + +!!! Note "Suggested template" + + Header: “Stop `{stop name and location}` is out of service” + + Description: “Due to {cause}, stop `{stop name and location}` will be out of service from`{start time}` to `{end time if applicable}`. Please use `{replacement stop}` instead.” + +--- + +## Station Closure + +Example of service change: + +* A station is closed for construction, including all of its platforms, entrances and exits. The train will continue through it but will not be able to pick-up or drop-off passengers. + +Effect: + +* `NO_SERVICE` + +Informed Entity: + +* `stop_id` of the station. + +Suggestions: + +* Add an alert that clearly mentions: + * That there is a station closure (in the header). + * The name of the affected station (in the header). + * The time period(s) that the service disruption spans (in the description, can be also additionally included in the header if it doesn’t make the header overlong). + +* If `tripUpdates` are provided, change `ScheduleRelationship` in the `StopTimeUpdate` of affected `stop_times` to SKIPPED if possible. +* Remove the `stop_ids` of the station platforms from the stop time entries in `[stop_times.txt](https://gtfs.org/documentation/schedule/reference/#stop_timestxt)` for trips that serve the closed station. This is more important if the incident extends over time (weeks to months). +* If it is certain that the station is going to be permanently closed, remove it and its child stops from the GTFS Schedule feed. Otherwise, you do not need to remove the station and its stops from `[stops.txt](https://gtfs.org/documentation/schedule/reference/#stopstxt)`. + +!!! Note "Suggested template" + + Header: “Station `{station name}` is out of service” + + Description: “Due to {cause}, station `{station name}` will be out of service from`{start time}` to `{end time if applicable}`. Please use `{bus replacement service or nearest in-service station}` instead.” + +--- + +## Detour + +Example of service change: + +* A bus route is deviated from its path, thereby moving the location of some stops. +* An NYC subway line is rerouted via the tracks of another line. + +Effect: + +* `DETOUR` + +Informed Entity: + +* `route_id` +* `direction_id` (direction of the detour). +* Include `stop_id` (`stop_ids` of the stops inside the segment that is deviated from). +* If only some trips are detoured during the incident, include `trip_id` if possible, using TripDescriptor . + +Suggestions: + +* Do not create a `DETOUR` alert if the detour does not move any stops and only changes the shape of a route. In that case, if the detour causes significant delays, treat the incident as a [`SIGNIFICANT_DELAYS` alert](#strong-delays). + +* Add an alert that clearly mentions: + * That there is a detour (in the header). + * The name of the affected route (in the header). + * Direction (in the header) + * The time period(s) that the service disruption spans (in the description, can be also additionally included in the header if it doesn’t make the header overlong). + * If the detour changes the location of some stops, mention the affected stops or the start and end stops of the affected segment (in the header and/or description). + * If the detour only changes the shape of the route but keeps all stops in their original locations, mention that the no stop is affected (in the header and/or description). + +* If `tripModifications` are provided, use `tripModifications` to indicate the `stop_ids` of the new stops and their new `stop_times` along with the propagated delay. Consult the [`tripModifications` reference](https://gtfs.org/documentation/realtime/feed-entities/trip-modifications/) for more information. +* If the detour is planned, make sure it is reflected in the GTFS Schedule feed. If the detour is unplanned and it extends over time, consider adding it to the GTFS Schedule feed once you have more certainty around it. + +!!! Note "Suggested template" + + Header: “Route `{route name}` is detoured between `{start stop}` and `{end stop}`” + + Description: “Due to `{cause}`, route/line `{route name}` is detoured. It will not serve the stops between `{start stop}` and `{end stop}` and will run through `{replacement streets/roads}` from`{start time}` to `{end time if applicable}`. Please use `{replacement stops}` instead.” + +--- + +## Short Turn + +Example of service change: + +* A TTC streetcar performs a short turn, it turns back in the opposite direction before completing all of its stops to balance service. + +Effect: + +* `NO_SERVICE` +* You may also use `MODIFIED_SERVICE` when you expect consumers to use the alert to adjust journey suggestions or routing, and when not doing so could result in presenting inaccurate information to riders. + +Informed Entity: + +* `route_id` +* `direction_id` (direction of the route). +* `trip_id` (using TripDescriptor) of the trip(s) where the short turn occurs. +* `stop_id` (`stop_ids` that will be skipped due to the short turn) + +Suggestions: + +* Add an alert that clearly mentions: + * That there is a short turn (in the header). + * The name of the affected route (in the header). + * Direction (in the header). + * The time period(s) that the service disruption spans (in the description, can be also additionally included in the header if it doesn’t make the header overlong). + * The affected trip(s) (in the description). + * The stops that will be skipped due to the short turn (in the header and/or description). + +* If `tripUpdates` are provided, change ScheduleRelationship in the `StopTimeUpdate` of affected `stop_times` to SKIPPED if possible. + +!!! Note "Suggested template" + + Header: “Route `{route name}` is short turning before `{stop name}`” + + Description: “Route/line `{route name}` is short turning before `{stop name}`. It will not serve the stops between `{start stop}` and `{end stop}`. The affected trips are `{human-readable trip identifier. e.g. Trip start time}`” + +--- + +## Stop Moved + +Example of service change: + +* Stop changes location temporarily due to construction. +* Stop is moved permanently (the alert can remain for a while for informative reasons). + +Effect: + +* `STOP_MOVED` + +Informed Entity: + +* `stop_id` (of the stop that changed location). + +Suggestions: + +* Add an alert that clearly mentions: + * That the stop is moved (in the header). + * The name of the stop (in the header). + * The new location of the stop (in the description). + * The time period(s) that the service change spans (in the description, can be also additionally included in the header if it doesn’t make the header overlong). + +* The alert might exist even when the stop was changed in the GTFS Schedule feed. (Just for informative reasons; could lead to mismatch issues as no `stop_id` in GTFS). +* If the alert is planned or extends over time (weeks to months), consider updating `stops.txt` and `[stop_times.txt](https://gtfs.org/documentation/schedule/reference/#stop_timestxt)` to reflect the new stop. + +!!! Note "Suggested template" + + Header: “Stop `{stop name and location}` is moved” + + Description: “Due to {cause}, stop `{stop name and location}` is moved `{definitely or indefinitely until {end time if applicable}}` to `{new location}`.” + +--- + +## Light Delays + +Example of service change: + +* A bus route is experiencing small delays. + +Suggestions: + +* In `tripUpdates`, make sure that the `StopTimeUpdate` of affected `stop_times` is adjusted. +* Insignificant delays should be in `tripUpdates`, do not create an alert. + + --- + +## Strong Delays + +Example of service change: + +* A bus route is experiencing significant delays due to traffic. +* A detour is causing significant delays for a route. + +Effect: + +* `SIGNIFICANT_DELAYS` + +Informed Entity: + +* `route_id` +* `direction_id` (if route delays are only for one direction). + +Suggestions: + +* Add an alert that clearly mentions: + * That there are delays (in the header). + * The name of the affected route(s) (in the header and/or description). + * The time period(s) that the service disruption spans (in the description, can be also additionally included in the header if it doesn’t make the header overlong). + +* If `tripUpdates` are provided, make sure that the `StopTimeUpdate` of affected `stop_times` is adjusted. + +!!! Note "Suggested template" + + Header: “ Delayed service on route `{route name}`” + + Description: “Due to {cause}, route/line `{route name}` is experiencing delays up to `{estimated current delay}`.” + +--- + +## Special Schedule/Schedule Modification + +Example of service change: + +* Summer/winter schedule starts. +* Special schedule for a short-term occasion where headways change. + +Effect: + +* `MODIFIED_SERVICE` + +Informed Entity: + +* `route_id` (if the modified service affects a route). +* `direction_id` (if the modified service is along one direction only). + +Suggestions: + +* Add an alert that clearly mentions: + * That there is a special or modified service (in the header). + * The name(s) of the affected route(s) (in the header and/or description). + * The time period(s) that the service change spans (in the description, can be also additionally included in the header if it doesn’t make the header overlong). + +!!! Note "Suggested template" + + Header: “ Schedule adjustment for `{route names} from `{start time}` to {end time if applicable}`” + + Description: “Due to {cause: new service, short term change}, service is adjusted for `{routes names}` from `{start time}` to {end time if applicable}. Please refer to our website `{URL (also included in the URL field)}` for further details.” + + Or + + Description: “Due to {cause: new service, short term change}, `{routes names}` will run on a `{special schedule: holiday, weekend, etc}` schedule from `{start time}` to {end time if applicable}. Please refer to our website `{URL (also included in the URL field)}` for further details.” + +--- + +## Service Increase + +Example of service change: + +* Extra trains are running for a short term to cover a special occasion or an insufficient service. +* Increased service schedule for a bus to cover trip cancellations of a train. + +Effect: + +* `ADDITIONAL_SERVICE` + +Informed Entity: + +* `route_id` (if the increased service affects a route). +* `direction_id` (if the modified service is along one direction only). + +Suggestions: + +* Add an alert that clearly mentions: + * That the service is increased (in the header). + * The name(s) of the affected route(s) (in the header and/or description). + * The time period(s) that the service change spans (in the description, can be also additionally included in the header if it doesn’t make the header overlong). + +* If the additional trips are not added in the GTFS Schedule feed: + + * If `tripUpdates` are provided, and if the service increase is unscheduled and you cannot add to a GTFS Schedule feed before 7 days of the service change: In `tripUpdates`, add the new trips with `ScheduleRelationship` in `TripDescriptor` set as `NEW`. + * Do not overrely on GTFS realtime TripUpdates for adding trips if you can do it in the GTFS Schedule feed. + +!!! Note "Suggested template" + + Header: “ More trips running for `{route names}`” + + Description: “Due to `{cause: new service, short term change}`, more departures will run for `{routes names}` starting `{start time}` until `{end time if applicable}`. Please refer to our website `{URL (also included in the URL field)}` for further details.” + +--- + +## Service Cuts + +Example of service change: + +* Reduced bus service for the short term. + +Effect: + +* `REDUCED_SERVICE` + +Informed Entity: + +* `route_id` (if the service cut affects a route). +* `direction_id` (if the service cut is along one direction only). + +Suggestions: + +* Add an alert that clearly mentions: + * That the service is reduced (in the header). + * The name(s) of the affected route(s) (in the header and/or description). + * The time period(s) that the service change spans (in the description, can be also additionally included in the header if it doesn’t make the header overlong). + +* If the removed trips are not removed in the GTFS Schedule feed: + + * If `tripUpdates` are provided, and if the service cut is unscheduled and you cannot remove them from a GTFS Schedule feed before 7 days of the service change: In `tripUpdates`, change `ScheduleRelationship` in `TripDescriptor` of the affected trips to CANCELED if possible. + * Do not overrely on GTFS realtime TripUpdates for removing trips if you can do it in the GTFS Schedule feed. + +!!! Note "Suggested template" + + Header: “ Fewer trips running for `{route names}`” + + Description: “Due to {cause: new service, short term change}, fewer departures will run for `{routes names}` starting `{start time}` until {end time if applicable}. Please refer to our website `{URL (also included in the URL field)}` for further details.” + +--- + +## Accessibility Issue + +Example of service change: + +* A station elevator is out of commission. +* An accessibility ramp is blocked in a station. +* The accessibility ramp of a bus is blocked. + +Effect: + +* `ACCESSIBILITY_ISSUE` + +Informed Entity: + +* `route_id`, `trip_id` (using TripDescriptor) and `direction_id` if needed (if the accessibility issue occurs on a route vehicle). +* `stop_id` of the affected platforms and entrances/exits, and `direction_id` if needed. +* The `stop_id` of the station is not required, as the station can be found using the GTFS Schedule feed. + +Suggestions: + +* Add an alert that clearly mentions: + * That there is an accessibility issue (in the header). + * The time period(s) that the service disruption spans (in the description, can be also additionally included in the header if it doesn’t make the header overlong). + * If the accessibility issue occurs on a vehicle + * Mention the name(s) of the affected route(s) (in the header and/or description). + * Mention the direction of the affected route(s) (in the header and/or description). + * Mention an identifier of the exact trip on which the accessibility issue occurs if applicable (in the description). + * If the accessibility issue occurs in a station + * Mention the name of the affected station (in the header and/or description). + * Mention the platforms to which the access will be affected (in the description). + * Mention the exact pathway (elevator, ramp, etc) that was affected (in the description). + +!!! Note "Suggested template" + + Header: “`{station name}`: {pathway. e.g. Southbound platform elevator}` out of commission.” + + Description: “Due to `{cause: maintenance, mechanical error, etc}`, the `{pathway}` to the `{platform}` in `{station}` is not in service from `{start_time}` to `{end_time}`. Please use `{replacement pathway}` instead.” + +!!! Note "Suggested template" + + Header: “ `{route names}`: The vehicle on {human-readable trip identifier. e.g. trip start time} is not accessible” + + Description: “Due to `{cause: e.g. mechanical error}`, the vehicle operating under `{route names}` on the trip `{human-readable trip identifier}` is not accessible.”