Create shared pooling trips

    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:

    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.

    • CreateTrip() method: gRPC or REST
    • CreateTripRequest message: gRPC only

    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.

    Trip fields
    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:
    • Single destination: Set to SHARED or EXCLUSIVE .
    • Multi-destination: Set to EXCLUSIVE .
    • Back-to-back: Set to EXCLUSIVE .
    • Shared pooling: Set to SHARED .
    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 dropoff_point , this field can also be set later by calling UpdateTrip , but a multi-destination trip by definition contains intermediate destinations.

    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 CreateTrip or UpdateTrip . You can also update vehicle waypoints through the waypoints field with a call to UpdateVehicle . The service does not return this information on GetTrip calls due to privacy reasons.

    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() returns remainingWaypoints that contain:
      B Pickup → A Drop-off → B Drop-off .
    • Either getTrip() or the onTripRemainingWaypointsUpdated callback for Trip A returns remainingWaypoints that contain:
      B Pickup → A Drop-off .
    • Either getTrip() or the onTripRemainingWaypointsUpdated callback for Trip B returns remainingWaypoints that 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 
 ; 
 }

    What's next
    Create a Mobile Website
    View Site in Mobile | Classic
    Share by: