TripDescriptors for TripUpdate and VehiclePosition

To help users have successful trips, review and use Google Transit guidelines. When working with TripDescriptors for the TripUpdate and VehiclePosition entities, follow the guidelines below:

TripUpdate

Frequency-based TripDescriptors

When trip_id and start_time are within exact_time=1 interval, start_time must be later than the beginning of the interval by an exact multiple of headway_secs. The triplet (trip_id, start_date, start_time) uniquely identifies a trip. If start_date isn’t specified, it’s set to the local day, corresponding to the feed timestamp. If the trip isn’t in service on the specified date, trip update or vehicle position is ignored. 

start_time should be the scheduled start time. When included, start_time must stay the same in all TripDescriptors representing the same trip across all feeds. 

For example:

trip_update {
    trip {
      trip_id: "frequency-expanded-trip"
      start_time: "10:10:00"
      start_date: "20150525"
    }

StopTimeUpdates should be used to indicate adjustments to the actual first departure time for the first stop. Do not adjust the start_time.

For example:
We decide at 10 AM, May 25th 2015, that a trip with route_id=R and direction_id=0 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 (R, 0, 2015-05-25, 10:10:00), but provide a StopTimeUpdate with departure from the first stop at 10:13:00. 

Example code:

trip_update {
    trip {
         route_id: "R"
         direction_id: 0 
         start_date: "20150525"
         start_time: "10:10:00"
    }
    stop_time_update {
      stop_sequence: 1
      departure {
        delay: 180
      }
    }
}
Non-frequency-based TripDescriptors

If no start_date is specified, then that trip update or vehicle position message defaults to the trip happening within [-12h, +12h] from the feed timestamp.

You can specify start_date if service runs on the specified day according to static GTFS. You can also specify start_time, but it must be the same as the corresponding static GTFS feed. If an invalid start_date or start_time is specified, the corresponding trip update or vehicle position is ignored.

For example:

trip_update {
    trip {
      trip_id: "non_frequency-expanded-trip"
      start_date: "20160203"
    }
  }
 

If trip_id is unavailable, use the following fields:

trip_update {
    trip {
      route_id: "route1"
      direction_id: 0
      start_time: "10:10:00"
      start_date: "20160203"
    }
}

Note: You must provide valid route_id, direction_id, and start_time. Otherwise, the trip_update is discarded. Also, if the IDs resolve to a non-unique trip or a trip not in service, the vehicle position or trip update is discarded. For this matching method to work, the GTFS static feed must include direction_id.

 

Create a simple TripUpdate

If it's not feasible for your system to generate predictions for entire trips, ensure the accuracy of your GTFS-realtime feed by providing a simple TripUpdate feed.

You must follow a few basic requirements:

  • The TripUpdates feed should include the best-available prediction of the next upcoming StopTimeUpdate.
  • If possible, the feed should continue to include any previously visited stops. Use StopTimeUpdates to represent stops, with values indicating the final times of when the vehicle arrived or departed the stop.
  • Include a TripUpdate.timestamp of when the latest measurement of the associated vehicle was taken, if available.

What happens next

When you successfully create a TripUpdate, we support re-routing based on the realtime departure and arrival times provided through GTFS-realtime TripUpdate feeds.

For example:
Trip T is scheduled to depart at 7 PM today from station S. The GTFS-realtime TripUpdate feed indicates that the trip has a delay of 5 minutes at station S. Now, when you search for connections from station S at 7:03 PM, trip T will show as one of the possible connections. This is because the realtime TripUpdate updated the departure time of trip T as being after the scheduled departure time.

Example code:

trip_update {
    trip {
      trip_id: "T"
      start_time: "07:00:00"
    }
    stop_time_update {
      stop_id: "S"
      departure {
        delay: 300
      }
    }
}

VehiclePosition

Frequency and non-frequency-based TripDescriptors

Trip descriptors for VehiclePositions are flexible for both frequency and non-frequency-based trips. We request that you provide as much information as possible to identify the trip. At minimum, we request that you provide the route_id and the direction_id.

Frequency and non-frequency based VehicleDescriptors

VehicleDescriptor is necessary to track a trip’s vehicle over time. It should be unique for each feed, and stable during the trip duration. To ensure that the vehicle is trackable, provide the vehicle descriptor id.

 

Position and trip matching

Provide a timestamped VehiclePositions feed with a well-matched TripDescriptor and accurate position information. Only report vehicles that are in service (i.e. assigned to a block). Trip matching occurs when you provide the vehicle’s most updated position with the timestamp of the reading, the trip descriptor, and the vehicle descriptor.

Examples of valid VehiclePosition messages

Example 1 

The following code shows a basic route_id informed for trip descriptor:

vehicle_position {
    trip {
      route_id: "route1"
    }
    vehicle {
      id: "route1-v1"
    }
    position {
      latitude: 4066265190
      longitude: 3862204692
    }
    timestamp: 1458508943
  }
}

Example 2 

The following code shows Example 1 with additional trip information provided:

vehicle_position {
    trip {
      route_id: "route1"
      direction_id: "0"
      start_time: "10:10:00"
      start_date: "20160203"
 
    }
    vehicle {
      id: "route1-v1"
    }
    position {
      latitude: 4066265190
      longitude: 3862204692
    }
    timestamp: 1458508943
  }
}
Was this helpful?
How can we improve it?

Need more help?

Try these next steps: