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
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
andstart_date
fields are required to identify a trip from the static schedule. Thestart_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
anddirection_id
matching 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_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 provideroute_id
,direction_id
,start_date
,start_time
. For theroute_id
anddirection_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, useStopTimeUpdates
. - 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
}
}
}