Finding nearby drivers

As part of your On-demand Rides and Deliveries Solution, the Route Planning and Dispatch capability lets you find nearby drivers by providing a SearchVehicles API.

The SearchVehicles API lets you find available nearby drivers in your On-demand Rides and Deliveries Solution consumer app who are best suited to a task such as a ride or a delivery request. The SearchVehicles API returns a ranked list of drivers matching task attributes with attributes of vehicles in your fleet.

Task attributes can include:

  • Pickup and drop-off locations
  • Requested vehicle and trip types
  • Required capacity
  • Other required matching attributes

Vehicle attributes can include:

  • The last known location of a vehicle
  • The vehicle state, type, or capacity
  • Other custom attributes

Ranking is ordered by your choice of either ETA, distance, or straight line distance from the pickup point.

Note that you must have Fleet Engine Service Super User or Consumer SDK User privileges to use the SearchVehicles API. For more information, see Authentication and Authorization.

Using the SearchVehicles API

To use the SearchVehicles API:

  • Construct a SearchVehiclesRequest based on the task to be assigned.
  • Call the SearchVehicles API (vehicleService.searchVehicles) with the constructed request.
  • Process the SearchVehicleResponse returned from the API.

SearchVehiclesRequest fields

Use the following required attribute fields to construct a SearchVehiclesRequest:

Field Description
parent Required. Must be in the format providers/{provider}. The provider must be the Project ID (for example, sample-cloud-project) of the Google Cloud Project of which the service account making this call is a member.
vehicle_types Required. Types of vehicles requested, either AUTO, TWO_WHEELER, TAXI, TRUCK, BICYCLE, or PEDESTRIAN.
trip_types Required. Either EXCLUSIVE (one active trip at a time per driver) or SHARED (one or multiple trips at a time per driver).
minimum_capacity Required. The minimum remaining capacity of the vehicle for a new task, either for passengers or deliveries.
pickup_point Required. The pickup location of the task in lat/long coordinates.
dropoff_point Optional. The drop-off location of the task in lat/long coordinates. The field is required if trip_types contains TripType.SHARED.
pickup_radius_meters Required. The radius in meters of the vehicle search area from the pickup point.
order_by Required. Order vehicles by one the following:
  • PICKUP_POINT_ETA, the vehicle's ETA at the pickup point.
  • PICKUP_POINT_DISTANCE, the distance between the vehicle and the pickup point.
  • DROPOFF_POINT_ETA, the vehicle's ETA to complete the trip at the drop-off point.
  • PICKUP_POINT_STRAIGHT_DISTANCE, the straight-line distance (not in route) between the vehicle and the pickup point.
count Required. The maximum number of vehicles to return from 1 to 50.

Refer to the Reference documentation to see the full set of SearchVehicleRequestfields.

SearchVehiclesRequest examples

This section shows examples of how to construct a SearchVehiclesRequest.

For example, suppose you have a pickup task to be assigned at RestaurantX and four vehicles:

  • Vehicle 1, which is 3500m away from RestaurantX.
  • Vehicle 2, which is 100m away from RestaurantX and has an active trip with a pickup and drop off at locations A and B.
  • Vehicle 3, which is 200m away from RestaurantX and has one remaining drop off very far away.
  • Vehicle 4, which is 1000m away from RestaurantX.

The following SearchVehiclesRequest returns Vehicle 4:

Pickup at RestaurantX, radius = 1200m, order by PICKUP_POINT_ETA

The following SearchVehiclesRequest returns Vehicle 3 and 4:

Pickup at RestaurantX, radius = 1200m, order by PICKUP_POINT_ETA, is_back_to_back enabled

The following SearchVehiclesRequest returns Vehicle 2, 3, and 4:

Pickup at RestaurantX, radius = 1200m, order by PICKUP_POINT_ETA, current_trips_present = ALL

SearchVehiclesResponse fields

A SearchVehiclesResponse consists of a list of VehicleMatch entities, ranked by the specified order_by attribute in the SearchVehiclesRequest. Each VehicleMatch entity has the following fields:

Field Description
vehicle The Vehicle object, including the vehicle_id and Vehicle attributes.
vehicle_pickup_eta The vehicle's ETA at the pickup location of the new task. This is the driving ETA.
vehicle_pickup_distance_meter The distance in meters between the vehicle and the pickup location of the new task.
vehicle_pickup_straight_line_distance_meter The straight-line distance in meters between the vehicle and the pickup location of the new task.
vehicle_dropoff_eta The Timestamp of the vehicle ETA at the pickup location of the new task. Note that the ETA is the driving ETA.
vehicle_trips_waypoints A list of remaining waypoints, including pickup and drop-off points, for the active trips currently assigned to the vehicle.
vehicle_match_type The vehicle's trip type, either EXCLUSIVE, BACK_TO_BACK, CARPOOL, or CARPOOL_BACK_TO_BACK.

SearchVehicles Example

The following example shows how to use the SearchVehicles API:

static final String PROJECT_ID = "project-id";

VehicleServiceBlockingStub vehicleService =
    VehicleService.newBlockingStub(channel);

String parent = "providers/" + PROJECT_ID;
SearchVehiclesRequest searchVehiclesRequest = SearchVehiclesRequest.newBuilder()
    .setParent(parent)
    .setPickupPoint( // Grand Indonesia East Mall
        TerminalLocation.newBuilder().setPoint(
            LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
    .setDropoffPoint( // Balai Sidang Jkt Convention Center
        TerminalLocation.newBuilder().setPoint(
            LatLng.newBuilder().setLatitude(-6.213796).setLongitude(106.807195)))
    .setPickupRadiusMeters(2000)
    .setCount(10)
    .setMinimumCapacity(2)
    .addTripTypes(TripType.EXCLUSIVE)
    .addVehicleTypes(VehicleType.newBuilder().setCategory(Category.AUTO).build())
    .setCurrentTripsPresent(CurrentTripsPresent.ANY)
    .setFilter("attributes.on_trip=\"false\"")
    .setOrderBy(VehicleMatchOrder.PICKUP_POINT_ETA)
    .build();


try {
  SearchVehiclesResponse searchVehiclesResponse =
      vehicleService.searchVehicles(searchVehiclesRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

List<VehicleMatch> vehicleMatches =
    searchVehicleResponse.getMatchesList();

// Each VehicleMatch contains a Vehicle entity and information about the
// distance and ETA to the pickup point and drop-off point.