The Definitive Guide to GTFS Realtime

2. Introduction to Service Alerts

Service alerts are generally used by transit agencies to convey information that can not be conveyed using a trip update message (the GTFS-realtime trip update message is covered in Chapter 4. Introduction to Trip Updates).

For example, consider a bus stop that was to be closed for a period of time due to construction in the area. If the stop was to be closed for a long period of time, the transit agency could modify the long-term schedule (the GTFS feed). If the closure was unexpected and the stop will reopen later that day, the agency can reflect this temporary closure using trip updates in the GTFS-realtime feed (instructing each relevant trip to skip that stop).

However, in both of these cases the reason why there were no trips visiting the stop has not been conveyed. Using a service alert, you can explain why the stop is closed and when it will reopen.

You can attach one or more entities to a service alert (such as routes, trips or stops). In the above example of a stop being closed, you could include its stop ID as it appears in the corresponding GTFS feed, thereby allowing apps consuming the feed to display a message to their users.

Examples of Service Alerts

Some examples of common service alerts used by agencies include:

• Holiday schedules. If there is an upcoming holiday, agencies may use service alerts to remind travelers that a holiday schedule will be applied that day.
• Stop closing. If a stop is closed (temporarily or permanently) customers may be notified using a service alert. In this instance, the alert can be linked to the stop that is closing. If it is being replaced by a new stop, the new stop may also be linked.
• Route detour. Service alerts can be used to indicate that for a period of time in the future a route will be redirected, perhaps due to a road closure. In this instance, the alert would link to stops that lie on the closed part of the road, as well as to routes that will detour as a result of the closure.
• Change to schedule. If an upcoming change to a schedule results in far less (or far more) services operating a stop, service alerts might be used to notify customers.
• Vehicle broken down. If a bus has broken down, or if electric trains are not moving due to a power outage, passengers can be notified using service alerts. In this instance, the alert could link to a specific trip, or it could be more general and instead link to its route or to the stops affected.

The EntitySelector type described shows how service alerts can be linked to routes, trips and stops accordingly.

Sample Feed

The following extract is from the service alerts feed of TriMet in Portland (http://developer.trimet.org/GTFS.shtml). It contains a single GTFS-realtime service alert entity. An entity contains either a service alert, a vehicle position or a trip update. This service alert indicates that a tree has fallen, causing potential delays to two routes.

Note: This extract has been converted from its binary format into a human-readable version. Outputting Human-Readable GTFS-realtime Feeds illustrates how this is achieved.

entity {
  id: "35122"
  
  alert {
    active_period {
      start: 1415739180
      end: 1415786400
    }
  
    informed_entity {
      route_id: "19"
      route_type: 3
    }
    
    informed_entity {
      route_id: "71"
      route_type: 3
    }
    
    url {
      translation {
        text: "http://trimet.org/alerts/"
      }
    }
    
    description_text {
      translation {
        text: "Expect delays due to a tree down blocking northbound 52nd at Tolman. Police are flagging traffic thru using the southbound lane."
      }
    }
  }
}

The elements of this service alert entity are as follows.

• Active Period
• Informed Entity
• URL
• Description text

Each of these fields are discussed below, as are some ways this particular feed could be improved.

Active Period

The active period element in this example states that the alert is active between 12:53 PM on one day and 2:00 AM the following day (Portland time). It is likely they included this finishing time to say "this might last all day, but it definitely won't be a problem tomorrow".

Often precise timing isn't known. If the active period is omitted, then the alert is assumed to be active for as long as it appears in the feed.

Informed Entity

In a GTFS-realtime service alerts feed, informed entity refers to a route, trip, stop, agency or route type, or any combination of these.

In this example, there are two informed entities, both of which are bus routes (as indicated by a route type of 3). Referring to the TriMet GTFS feed (http://developer.trimet.org/schedule/gtfs.zip), the routes with an ID of 19 and 71 are as follows.

route_id,route_short_name,route_long_name,route_type
19,19,Woodstock/Glisan,3
71,71,60th Ave/122nd Ave,3

Technically in this case the route_type value need not be specified, as this can be derived using the GTFS feed. Sometimes, however, an alert may impact all routes for a given mode of transport, so the route type would be specified only.

For instance, if an electrical outage affects all subway trains, then an informed entity containing only a route type of 1 (the GTFS value for Subway routes) would be sufficient, rather than including a service alert for each subway route.

URL

This field contains a web address where additional information about the alert can be found.

In this particular example, TriMet has included a generic URL for their service alert. Other alerts in the same feed also use the same URL. It would be far more useful if instead each alert pointed to a URL specifically related to that alert. This would make it easier to provide the end user with additional information specific to that alert.

Description Text

This field contains a textual description of the alert that can be presented to the users of your web site or app. Just like the URL field, it has a type of TranslatedString, which is the mechanism by which GTFS-realtime can provide translations in multiple languages if required.

Improvements

In addition to providing a more specific URL, this alert could be improved by including values for the cause and effect fields. For instance, cause could have a value of WEATHER or ACCIDENT, while effect could have a value of DETOUR or SIGNIFICANT_DELAYS.

Additionally, this alert could include the header_text field to complement the description_text field. This would allow you to display a summary of the alert (header_text), then supply more information if the user of your app or web site requests it (description_text).

Specification

This section contains the specification for the Alert entity type. Some of this information has been sourced from the GTFS-realtime reference page (https://developers.google.com/transit/GTFS-realtime/reference).

Alert

An Alert message makes it possible to provide extensive information about a given service alert, including the ability to match it to any number of routes, stops or trips.

The fields for any single service alert are as described in the following table.

The following values are valid for the Cause enumerator:

• ACCIDENT
• CONSTRUCTION
• DEMONSTRATION
• HOLIDAY
• MAINTENANCE
• MEDICAL_EMERGENCY
• POLICE_ACTIVITY
• STRIKE
• TECHNICAL_PROBLEM
• WEATHER
• UNKNOWN_CAUSE
• OTHER_CAUSE

The following values are valid for the Effect enumerator:

• ADDITIONAL_SERVICE
• NO_SERVICE
• SIGNIFICANT_DELAYS
• DETOUR
• STOP_MOVED
• MODIFIED_SERVICE
• REDUCED_SERVICE
• UNKNOWN_EFFECT
• OTHER_EFFECT

TimeRange

A TimeRange message specifies a time interval. It is not mandatory to include both the start and finish times, but at least one of those is required if a TimeRange is included.

If only the start time is specified, the time range is considered active after the starting time.

If only the end time is specified, the time range is considered active before the end time.

If both the start and finish times are specified, the time range is considered active between these times.

EntitySelector

An EntitySelector message is used to specify an entity from within a GTFS feed. Doing so allows you to match up a service alert with a route (or all routes of a given type), trip, stop or agency from the GTFS feed that corresponds to the GTFS-realtime feed.

All of these elements are optional, but at least one of them must occur. If multiple elements are specified, then all must be matched.

Note: Conversely, if you want multiple matches, then you should instead include multiple EntitySelector values. For instance, if you want a service alert that covers all buses and ferries, then the informed_entity field would contain one EntitySelector for buses, and another for ferries.

The following table shows some different combinations that can occur, and what each of them mean.

As this demonstrates, it is possible to match service alerts to real-world entities in any number of ways. This allows you to keep relevant users informed. The alternative to matching on this granular level would be to show all of your users all service alerts, meaning most alerts would be irrelevant to most people.

TripDescriptor

One of the files in a GTFS feed is frequencies.txt, which is used to specify trips that repeat every x minutes. This file is used when an agency does not have a specific schedule for trips, other than guaranteeing, for instance, that a new trip departs every five minutes.

For example, it is possible for a particular route to run every five minutes for an entire day, while only having one entry in trips.txt (and one set of corresponding stop times in stop_times.txt).

When using trip frequencies the trip_id value may not be enough to uniquely identify a single trip from the GTFS feed. This means that in order to match a trip, additional information may need to be supplied, which the TripDescriptor message allows for.

The following values are valid for the ScheduleRelationship enumerator:

• SCHEDULED. Used when the trip being described is running in accordance with a trip in the GTFS feed.
• ADDED. A trip that was added in addition to the schedule. For instance, if an extra trip was added because there were more passengers than normal, it would be represented using this value.
• UNSCHEDULED. A trip that is running with no schedule associated with it. For instance, if this trip is expected to run but there is no static schedule associated with it, it would be marked with this value.
• CANCELED. A trip that existed in the schedule but was removed. For example, if a vehicle broke down and could not complete the trip, then it would be marked as canceled.

If a trip has been added, then the route_id should be populated, as without this it may not be possible to determine which route the added trip corresponds to (since the trip_id value would not appear in the GTFS trips.txt file).

With the newly-added direction_id field (still experimental at time of writing this book), an added trip can also have its direction specified, meaning you can present information to your users about which direction the vehicle is traveling, even if you do not know its specific stops.

TranslatedString

A TranslatedString message contains one or more Translation elements. This allows for alerts to be issued in multiple languages. A Translation element is structured as follows.