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_idstart_timestart_date
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_idandstart_datefields are required to identify a trip from the static schedule. Thestart_timefield 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_idanddirection_idmatching method to work, the GTFS static feed should includedirection_ids. This matching method isn't well supported because it's done on a best effort basis and is subject to change.
- For the
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_timeis 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 provideroute_id,direction_id,start_date,start_time. For theroute_idanddirection_idmatching 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_timefield should be the same as the scheduled start time from the static dataset. - The
start_timemust stay the same in all TripDescriptors that represent the same trip across all feed bundles. - Don't adjust the
start_timeto indicate adjustments to the first departure time for the first stop. Instead, useStopTimeUpdates. - While the
start_timeshould 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
}
}
}