The Definitive Guide to GTFS Realtime

4. Introduction to Trip Updates

A trip update message is used to report the progress of a vehicle along its trip. Each trip may only have one trip update message in a GTFS-realtime feed.

A trip update can report that a trip has been canceled, or it can update the progress of any number of stops on the trip. For example, a trip update may contain an arrival estimate only for the vehicle's next stop, or it may contain estimates for every remaining stop on the trip.

If a trip does not have a trip update message, this should be interpreted as there being no real-time information available; not that it is necessarily progressing as scheduled.

Sample Feed

The following extract is from the MBTA trip update feed (https://openmobilitydata.org/p/mbta/91). MBTA also provide separate feeds for service alerts and vehicle positions.

This extract contains a single GTFS-realtime entity, which represents a bus that is four minutes behind schedule (a delay value of 240 seconds).

entity {
  id: "25732950"
  
  trip_update {
    trip {
      trip_id: "25732950"
      start_date: "20150120"
      schedule_relationship: SCHEDULED
      route_id: "08"
    }
    
    stop_time_update {
      stop_sequence: 43
      arrival {
        delay: 240
      }
      stop_id: "135"
    }
    
    vehicle {
      id: "y2189"
      label: "2189"
    }
  }
}

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

The elements of a trip_update entity are as follows.

Trip

This element is used to identify the particular trip that a trip update applies to. In this instance, the trip has an ID of 25732950, running on the service day of 20 January 2015.

Note: Although this trip may no longer be active, you can view similar trips at https://openmobilitydata.org/p/mbta/64/latest/route/8.

Since the schedule_relationship value is SCHEDULED, this trip corresponds to a trip in the MBTA GTFS file (https://openmobilitydata.org/p/mbta/64).

If the schedule_relationship value is ADDED, then this corresponds to a new trip for the route with an ID of 08. The stop_time_added field would likely then contain an entry for each stop on the added trip.

Note: The trip could also be marked as CANCELED. If so, the trip could either be in the GTFS feed or it may have been added through a previous trip update message.

Stop Time Update

The stop_time_update elements contains information specific to a stop on the trip. It is repeated for each stop that there is information for. If the trip has been canceled (indicated by a schedule_relationship value of CANCELED) then there will no stop_time_update elements.

In the above sample, there is a single update, corresponding to the stop with an ID of 135. You can look up the details of this stop at https://openmobilitydata.org/p/mbta/64/latest/stop/135. This stop has a stop sequence of 43, as shown in the following figure.

Referring to the stop_times.txt file in the GTFS feed, the scheduled arrival time for this trip at stop 135 is 6:12 PM. The delay value indicates that it will be four minutes late (240 seconds), meaning it will now arrive at 6:16 PM.

As there are no additional stop time updates for subsequent updates, it can be assumed that this delay carries through to the rest of the trip. There are eight remaining stops after this one, so all of those will also be four minutes late.

Vehicle

The vehicle information is useful as it enables you to identify specific vehicles. In this instance, MBTA use the same identifier both as their internal identifier and also as the identifier printed on the bus. This sample once again refers to bus 2189. The photograph in Chapter 3: Vehicle Positions shows how this number appears on the vehicles.

Specification

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

TripUpdate

TripDescriptor

Identifying a trip in a trip update is slightly different to identifying a trip in a service alert or vehicle position message. With vehicle positions and service alerts, the trip descriptor may refer to an arbitrary trip for a given route, but to do so with trip updates does not make sense.

With trip updates, you must be able to identify a specific trip from the corresponding GTFS feed. This is because trip updates will often only include an update for a single stop, and you must therefore determine subsequent stop times for a given trip so those can be adjusted accordingly. To do so, you need to be able to find a specific trip and its corresponding stop times in the GTFS feed.

This differs to a service alert where you can apply an alert to all trips for a given route, rather than one at a specific time. It also differs to vehicle positions, where being able to see all positions for a route on a map is useful, even if you do not know the specific trip each position corresponds to.

VehicleDescriptor

This element is used to identify a specific vehicle, both internally and for passengers. Every single vehicle in the system must have its own identifier, and it should carry across all vehicle positions and trip updates that correspond to the specific vehicle.

StopTimeUpdate

Valid values for the ScheduleRelationship enumerator are:

StopTimeEvent

Either the delay or exact time must be specified. If both are specified, then the scheduled time in GTFS added to the delay should equal the time value. If it does not, just the time value can be used.

Conversely, if the delay value is not specified, you can calculate it by subtracting the GTFS scheduled time from the predicted time value.

Note: Your interpretation of what constitutes a delay is likely to depend on how you are presenting real-time data. For instance, if you present arrivals to your users as "Early", "On-Time" and "Late", it is likely to be more useful to your users to indicate a 30-second delay as being "On-Time" rather than "Late".

The uncertainty field is used to indicate the accuracy of the prediction. For example, consider a prediction that indicates a bus will be five minutes late. If the transit agency thinks the prediction is within a minute on either side of five minutes (say, 4-6 minutes late), then the uncertainty value is the difference between the minimum and maximum value. In this example, the uncertainty is 2 minutes -- a value of 120 seconds.