Buscar vehículos

Como parte del servicio de viajes de movilidad on demand, puedes encontrar vehículos cercanos con el método SearchVehicles.

El método SearchVehicles te permite encontrar vehículos cercanos disponibles en tu app para consumidores que sean más adecuados para un viaje o una solicitud de entrega específicos. La API de SearchVehicles devuelve una lista clasificada de vehículos cuyos atributos coinciden con los atributos del viaje solicitado. La clasificación se ordena según tu elección de hora estimada de llegada, distancia o distancia en línea recta desde el punto de partida.

Atributos de búsqueda	Atributos del vehículo
Ubicaciones de partida y llegada Tipos de vehículos y viajes solicitados Capacidad requerida Otros atributos de coincidencia obligatorios	La última ubicación conocida de un vehículo El estado, el tipo o la capacidad del vehículo Otros atributos personalizados

Nota: Debes tener privilegios de administrador de Fleet Engine On-demand o de usuario del SDK para consumidores para usar la API de SearchVehicles. Para obtener más información, consulta Roles de la cuenta de servicio de Fleet Engine.

Usa el método SearchVehicles

Para usar SearchVehicles, sigue este proceso general:

1. Crea un SearchVehiclesRequest según el viaje que se asignará.
2. Llama a la API de SearchVehicles (vehicleService.searchVehicles) con la solicitud construida.
3. Procesa el SearchVehicleResponse que se muestra desde la API.

Campos de SearchVehiclesRequest

Usa los siguientes campos de atributos obligatorios para construir un SearchVehiclesRequest:

Campo	Descripción
elemento superior	Obligatorio. Debe tener el formato providers/{provider}. El proveedor debe ser el ID del proyecto de Google Cloud del que es miembro la cuenta de servicio que realiza esta llamada.
vehicle_types	Obligatorio. Son los tipos de vehículos solicitados, que pueden ser AUTO, TWO_WHEELER, TAXI, TRUCK, BICYCLE o PEDESTRIAN.
trip_types	Obligatorio. Puede ser EXCLUSIVE (un viaje activo a la vez por conductor) o SHARED (uno o varios viajes a la vez por conductor).
minimum_capacity	Obligatorio. Es la capacidad mínima restante del vehículo para un viaje nuevo, ya sea para pasajeros o entregas.
pickup_point	Obligatorio. Es la ubicación de recogida del viaje en coordenadas de latitud y longitud.
dropoff_point	Opcional. Es la ubicación de destino del viaje en coordenadas de latitud y longitud. Este campo es obligatorio si trip_types contiene TripType.SHARED.
pickup_radius_meters	Obligatorio. Es el radio en metros del área de búsqueda de vehículos desde el punto de partida.
order_by	Obligatorio. Ordena los vehículos por uno de los siguientes criterios: PICKUP_POINT_ETA: Es la hora estimada de llegada del vehículo al punto de partida. PICKUP_POINT_DISTANCE, la distancia entre el vehículo y el punto de partida DROPOFF_POINT_ETA: Es la hora estimada de llegada del vehículo para completar el viaje en el punto de destino. PICKUP_POINT_STRAIGHT_DISTANCE, la distancia en línea recta (no en la ruta) entre el vehículo y el punto de partida.
count	Obligatorio. Es la cantidad máxima de vehículos que se devolverán, de 1 a 50.
filter	Opcional. Es una consulta de filtro que se aplica cuando se buscan vehículos.
maximum_staleness	Opcional. Restringe la búsqueda solo a los vehículos que enviaron ubicaciones actualizadas a Fleet Engine dentro de la duración especificada. Si no se establece este campo, el servidor usa cinco minutos como valor predeterminado.

Consulta la documentación de referencia para ver el conjunto completo de campos de SearchVehicleRequest.

Situaciones de SearchVehiclesRequest

En esta sección, se muestran ejemplos de cómo construir un SearchVehiclesRequest.

Por ejemplo, supongamos que un cliente quiere que lo recojan en el RestauranteX y tienes cuatro vehículos:

• Vehículo 1: Se encuentra a 3,500 m del RestauranteX.
• Vehículo 2: Se encuentra a 100 m de RestaurantX con un viaje activo que incluye un retiro y una entrega en las ubicaciones A y B.
• Vehículo 3: Está a 200 m del RestaurantX y tiene una entrega restante muy lejos.
• Vehículo 4: Se encuentra a 1,000 m de RestaurantX.

A continuación, se muestran varias solicitudes según el vehículo que devuelven.

Devuelve el vehículo 4

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

Devuelve los vehículos 3 y 4.

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

Devuelve los vehículos 2, 3 y 4

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

Campos de SearchVehiclesResponse

Un SearchVehiclesResponse consiste en una lista de entidades VehicleMatch, clasificadas por el atributo order_by especificado en SearchVehiclesRequest. Cada entidad VehicleMatch tiene los siguientes campos:

Campo	Descripción
vehículo	El objeto Vehicle, incluidos los atributos vehicle_id y Vehicle.
vehicle_pickup_eta	La hora estimada de llegada del vehículo a la ubicación de partida si este viaje se asignara al vehículo en este momento.
vehicle_pickup_distance_meter	Es la distancia en metros entre el vehículo y la ubicación de partida del viaje nuevo.
vehicle_pickup_straight_line_distance_meter	Es la distancia en línea recta en metros entre el vehículo y la ubicación de partida del viaje nuevo.
vehicle_dropoff_eta	Es la hora estimada de llegada del vehículo a la ubicación de entrega si este viaje se asignara al vehículo en este momento.
vehicle_trips_waypoints	Es una lista de los puntos de referencia restantes, incluidos los puntos de partida y de llegada, para los viajes activos asignados actualmente al vehículo.
vehicle_match_type	Es el tipo de viaje del vehículo, que puede ser EXCLUSIVE, BACK_TO_BACK, CARPOOL o CARPOOL_BACK_TO_BACK.

Para obtener una lista completa de los campos de VehicleMatch, consulta los siguientes recursos:

• VehicleMatch message (gRPC)
• VehicleMatch resource (REST)

Nota: Un vehículo debe estar en línea (con vehicle_state=ONLINE) para que se pueda buscar y SearchVehicles lo devuelva.

Usa consultas de filtro

SearchVehicles y ListVehicles admiten el filtrado de atributos de vehículos con una consulta de filtro.

Las consultas de filtro SOLO admiten el filtrado de atributos personalizados para vehículos y no se pueden usar para otros campos. Cuando se usa en una búsqueda que incluye otros criterios de campo, como minimum_capacity o vehicle_types, la consulta de filtro funciona como una cláusula AND.

Por ejemplo, si buscas un vehículo que tenga una capacidad mínima de 6 pasajeros y filtras un attributes, como que se admitan mascotas, tus criterios solo mostrarán los vehículos que admitan mascotas y puedan transportar al menos 6 pasajeros.

Para conocer la sintaxis de las consultas de filtro, consulta AIP-160 y ver ejemplos. Para obtener detalles sobre cómo crear atributos de vehículos, consulta el campo de atributos de vehículos en la guía Actualiza los campos de vehículos.

Nota: Como práctica recomendada, evita el uso de los siguientes campos de atributos cuando emitas una consulta de filtro: required_attributes, required_one_of_attributes o required_one_of_attributes_sets. En su lugar, usa el campo filter, que reemplaza esos campos. Además, recibirás un error si tu solicitud especifica un valor tanto en el campo filter como en los otros campos de atributos.

Ejemplo de SearchVehicles

En el siguiente ejemplo, se muestra cómo usar la API de SearchVehicles con la biblioteca de gRPC de Java. Para obtener una lista completa de los lenguajes compatibles, consulta Bibliotecas cliente para servicios de viajes on demand.

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.

¿Qué sigue?

• DeleteVehicle