Select a trip with TripDescriptor

Important: For the duration of the trip, don’t change the TripDescriptor. TripDescriptor is used for the selection of a single trip.

To link a realtime trip to its static General Transit Feed Specification (GTFS) prototype, the TripDescriptor submessage is used. This article explains how to select a trip for the schedule_relationship as “SCHEDULED” or “CANCELED.”

Add or match a trip

To add a trip in realtime with the schedule_relationship as “ADDED,” refer to Add a trip in realtime.

To match a trip between realtime and a static dataset, in TripDescriptor, you should include a tuple:

• trip_id
• start_time
• start_date

If you don’t have the trip_id, you can substitute it for the route_id and the direction_id. For correct matches, the start_time and start_date are required.

Provide TripDescriptor for non-frequency & frequency schedules

Non-frequency based TripDescriptors

• Both trip_id and start_date fields are required to identify a trip from the static schedule. The start_time field is optional. If it’s provided, it must match with one of the trip’s start times on the given start date from the static schedule.
• If you can’t provide the trip_id, then you must provide <route_id, direction_id, start_date>.
  • For the route_id and direction_id matching method to work, the GTFS static feed should include direction_ids. This matching method isn't well supported because it's done on a best effort basis and is subject to change.

Example code

trip_update {

    trip {

      trip_id: "non_frequency-expanded-trip"

      start_date: "20160203"

    }

  }

trip_update {

    trip {

      route_id: "route1"

      direction_id: 0

      start_time: "10:10:00"

      start_date: "20160203"

    }

}

Frequency-based TripDescriptors

Frequency-based trips are modeled with frequencies.txt. For these types of trips, the start_time field is required because a specific time component is required to identify an individual trip.

• To identify a trip from the static schedule, a tuple of trip_id, start_date, start_time is required. If there’s missing information, we may use our best effort to match a trip.
• If you can’t provide the trip_id, then you must provide route_id, direction_id, start_date, start_time. For the route_id and direction_id matching method to work, the GTFS static feed should include direction_ids. This matching method is not well supported.

When you provide a start_time, consider the following:

• The start_time field should be the same as the scheduled start time from the static dataset.
• The start_time must stay the same in all TripDescriptors that represent the same trip across all feed bundles.
• Don't adjust the start_time to indicate adjustments to the first departure time for the first stop. Instead, use StopTimeUpdates.
• While the start_time should be close to the departure time from the first station, it doesn’t have to be equal to the departure time.

Tip: When trip_id and start_time are within an exact_time=1 interval, the start_time must be later than the beginning of the interval by an exact multiple of headway_secs.

Example

We decide at 10 AM, May 25th 2015, that a trip with trip_id=T will start at start_time=10:10:00. We provide this information via realtime feed at 10:01. At 10:05, we realize that the trip will start at 10:13 instead of 10:10. In our new realtime feed, we can still identify this trip as (T, 2015-05-25, 10:10:00), but provide a StopTimeUpdate with the departure from the first stop at 10:13:00.

If the start_time is changed, it might result in declaring a second bus departure. In this scenario, one departure is at 10:10 and another is declared at 10:13.

Example code:

trip_update {

    trip {

         trip_id: “T”

         start_date: "20150525"

         start_time: "10:10:00"

    }

    stop_time_update {

      stop_sequence: 1

      departure {

        delay: 180

      }

    }

}