On-demand Rides and Deliveries Solution is currently available only to select partners. Contact sales to learn more.

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 attribute fields to construct a SearchVehiclesRequest:

Field Description
vehicle_types Required. Types of vehicles requested, either AUTO or TWO_WHEELER.
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.
pickup_radius_meters Required. The radius in meters of the vehicle search area from the pickup point.
include_back_to_back Optional. For ridesharing, includes vehicles that are still on another active trip if there is one remaining drop off.
current_trip_present Optional. Includes vehicles based on whether they have a current active trip, either NONE (no current active trip) or ANY (any number of current active trips).

Note: You can't use current_trip_present with include_back_to_back. Setting include_back_to_back to true and current_trip_present to either NONE or ANY generates an error.
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.

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)
    .addRequiredAttributes(
        VehicleAttribute.newBuilder().setKey("on_trip").setValue("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.