This document describes how to create a shared pooling trip, set the correct fields, and assign it to a vehicle to fulfill. It assumes you have set up Fleet Engine, you have created vehicles, have a working driver app, and optionally, a consumer app. You should also be familiar with the various trip scenarios available for on-demand trips. See the following related guides for that:
- Set up Fleet Engine
- Create a vehicle
- Trip scenarios in the On-demand trips overview
Trip creation basics
This section describes the request details necessary for creating a trip in Fleet Engine. You issue a creation request using either gRPC and REST.
Trip Fields
Use the following fields to create a trip in Fleet Engine. You can use different fields for the different kinds of trips: single- or multi-destination, back-to-back, or shared pooling trips. You can supply the optional fields when you create the trip, or you can set them later when you update the trip.
| Name | Required? | Description |
|---|---|---|
| parent | Yes | A string that includes the project ID. This ID must be the same ID used across your entire Fleet Engine integration, with the same service account roles. |
| trip_id | Yes | A string that you create that uniquely identifies this trip. Trip IDs have certain restrictions, as indicated in the reference. |
| trip_type | Yes | Set the TripType to the following values for the trip type you're creating:
|
| pickup_point | Yes | The trip's point of origin. |
| Intermediate destinations | Yes | Multi-destination trips only: The list of intermediate destinations that the driver visits in between
pickup and drop-off. As with |
| vehicle_waypoints | Yes | Shared-pooling trips only: This field supports interleaving the waypoints from multiple trips.
It contains all of the remaining waypoints for the assigned vehicle, as well
as the pickup and drop-off waypoints for this trip. You can set this field
by calling |
| number_of_passengers | No | The number of passengers on the trip. |
| dropoff_point | No | The trip's destination. |
| vehicle_id | No | The ID of the vehicle assigned to the trip. |
Example: create a shared pooling trip
The following backend integration sample demonstrates how to create a trip and assign it to a vehicle as a shared-pooling trip.
// Vehicle with VEHICLE_ID ID is already created and it is assigned Trip A.
static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_ID = "shared-trip-A";
static final String VEHICLE_ID = "your-vehicle-id";
static final String TRIP_A_ID = "trip-a-id";
static final String TRIP_B_ID = "trip-b-id";
TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);
String parent = "providers/" + PROJECT_ID;
LatLng tripBPickup =
LatLng.newBuilder().setLatitude(-12.12314).setLongitude(88.142123).build();
LatLng tripBDropoff =
LatLng.newBuilder().setLatitude(-14.12314).setLongitude(90.142123).build();
TerminalLocation tripBPickupTerminalLocation =
TerminalLocation.newBuilder().setPoint(tripBPickup).build();
TerminalLocation tripBDropoffTerminalLocation =
TerminalLocation.newBuilder().setPoint(tripBDropoff).build();
// TripA already exists and it's assigned to a vehicle with VEHICLE_ID ID.
Trip tripB = Trip.newBuilder()
.setTripType(TripType.SHARED)
.setVehicleId(VEHICLE_ID)
.setPickupPoint(tripBPickupTerminalLocation)
.setDropoffPoint(tripBDropoffTerminalLocation)
.addAllVehicleWaypoints(
// This is where you define the arrival order for unvisited waypoints.
// If you don't specify an order, then the Fleet Engine adds Trip B's
// waypoints to the end of Trip A's.
ImmutableList.of(
// Trip B's pickup point.
TripWaypoint.newBuilder()
.setLocation(tripBPickupTerminalLocation)
.setTripId(TRIP_B_ID)
.setWaypointType(WaypointType.PICKUP_WAYPOINT_TYPE)
.build(),
// Trip A's drop-off point.
TripWaypoint.newBuilder()
.setLocation(tripA.getDropoffPoint())
.setTripId(TRIP_A_ID)
.setWaypointType(WaypointType.DROP_OFF_WAYPOINT_TYPE)
.build(),
// Trip B's drop-off point.
TripWaypoint.newBuilder()
.setLocation(tripBDropoffTerminalLocation)
.setTripId(TRIP_B_ID)
.setWaypointType(WaypointType.DROP_OFF_WAYPOINT_TYPE)
.build()))
.build();
// Create Trip request
CreateTripRequest createTripRequest = CreateTripRequest.newBuilder()
.setParent(parent)
.setTripId(TRIP_B_ID)
.setTrip(tripB)
.build();
try {
// createdTrip.remainingWaypoints will contain shared-pool waypoints.
// [tripB.pickup, tripA.dropoff, tripB.dropoff]
Trip createdTrip = tripService.createTrip(createTripRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
Update shared pooling trips
Any trip created in Fleet Engine must be assigned to a vehicle in order for Fleet Engine to calculate trip ETAs and track it. You can do this either during trip creation or later when you update the trip.
For shared pooling trips, you must specify an order to the unvisited waypoints
in the trip's collection of vehicle waypoints (Trip.vehicle_waypoints). Fleet
Engine uses this list to automatically update the trip waypoints for all trips
in the shared-pool.
For example, consider two shared-pool trips, Trip A and Trip B:
- Trip A is enroute to its drop-off location.
- Trip B is then added to the same vehicle.
In one UpdateTripRequest for Trip B,
you set the vehicleId, and also set Trip.vehicle_waypoints to the optimal
waypoint order: B Pickup
→ A Drop-off →
B Drop-off.
- Calling
getVehicle()returnsremainingWaypointsthat contain:
B Pickup → A Drop-off → B Drop-off. - Either
getTrip()or theonTripRemainingWaypointsUpdatedcallback for Trip A returnsremainingWaypointsthat contain:
B Pickup → A Drop-off. - Either
getTrip()or theonTripRemainingWaypointsUpdatedcallback for Trip B returnsremainingWaypointsthat contain:
B Pickup → A Drop-off → B Drop-off.
Example
The following backend integration sample demonstrates how to update a trip with the vehicle ID and waypoints for two shared-pool trips.
static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_A_ID = "share-trip-A";
static final String TRIP_B_ID = "share-trip-B";
static final String VEHICLE_ID = "Vehicle";
String tripName = "providers/" + PROJECT_ID + "/trips/" + TRIP_B_ID;
// Get Trip A and Trip B objects from either the Fleet Engine or storage.
Trip tripA = …;
Trip tripB = …;
TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);
// The trip settings to update.
Trip trip = Trip.newBuilder()
.setVehicleId(VEHICLE_ID)
.addAllVehicleWaypoints(
// This is where you define the arrival order for unvisited waypoints.
// If you don't specify an order, then the Fleet Engine adds Trip B's
// waypoints to the end of Trip A's.
ImmutableList.of(
// Trip B's pickup point.
TripWaypoint.newBuilder()
.setLocation(tripB.getPickupPoint())
.setTripId(TRIP_B_ID)
.setWaypointType(WaypointType.PICKUP_WAYPOINT_TYPE)
.build(),
// Trip A's drop-off point.
TripWaypoint.newBuilder()
.setLocation(tripA.getDropoffPoint())
.setTripId(TRIP_A_ID)
.setWaypointType(WaypointType.DROP_OFF_WAYPOINT_TYPE)
.build(),
// Trip B's drop-off point.
TripWaypoint.newBuilder()
.setLocation(tripB.getDropoffPoint())
.setTripId(TRIP_B_ID)
.setWaypointType(WaypointType.DROP_OFF_WAYPOINT_TYPE)
.build()))
.build();
// The trip update request.
UpdateTripRequest updateTripRequest = UpdateTripRequest.newBuilder()
.setName(tripName)
.setTrip(trip)
.setUpdateMask(FieldMask.newBuilder()
.addPaths("vehicle_id")
.addPaths("vehicle_waypoints"))
.build();
// Error handling. If Fleet Engine has both a trip and vehicle with the IDs,
// and if the credentials validate, and if the given vehicle_waypoints list
// is valid, then the service updates the trip.
try {
Trip updatedTrip = tripService.updateTrip(updateTripRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND: // Either the trip or vehicle does not exist.
break;
case PERMISSION_DENIED:
break;
case INVALID_REQUEST: // vehicle_waypoints is invalid.
break;
}
return;
}