Pesquisar veículos

Como parte do serviço de viagens de mobilidade sob demanda, você pode encontrar veículos próximos usando o método SearchVehicles.

O método SearchVehicles permite encontrar veículos disponíveis nas proximidades no seu app para dispositivos móveis do consumidor que são mais adequados para uma corrida ou um pedido de entrega específico. A API SearchVehicles retorna uma lista classificada de veículos cujos atributos correspondem aos atributos da viagem solicitada. A classificação é ordenada de acordo com sua escolha de ETA, distância ou distância em linha reta do ponto de partida.

Atributos de pesquisa Atributos do veículo
  • Locais de embarque e desembarque
  • Tipos de veículo e viagem solicitados
  • Capacidade exigida
  • Outros atributos de correspondência obrigatórios
  • O último local conhecido de um veículo
  • O estado, o tipo ou a capacidade do veículo
  • Outros atributos personalizados

Use o método SearchVehicles

Para usar o SearchVehicles, siga este processo geral:

  1. Crie um SearchVehiclesRequest com base na viagem a ser atribuída.
  2. Chame a API SearchVehicles (vehicleService.searchVehicles) com a solicitação criada.
  3. Processe o SearchVehicleResponse retornado da API.

Campos SearchVehiclesRequest

Use os seguintes campos de atributos obrigatórios para construir um SearchVehiclesRequest:

Campo Descrição
primária Obrigatório. Precisa estar no formato providers/{provider}. O provedor precisa ser o ID do projeto do Google Cloud de que a conta de serviço que faz essa chamada é membro.
vehicle_types Obrigatório. Tipos de veículos solicitados: AUTO, TWO_WHEELER, TAXI, TRUCK, BICYCLE ou PEDESTRIAN.
trip_types Obrigatório. EXCLUSIVE (uma viagem ativa por vez por motorista) ou SHARED (uma ou várias viagens por vez por motorista).
minimum_capacity Obrigatório. A capacidade mínima restante do veículo para uma nova viagem, seja para passageiros ou entregas.
pickup_point Obrigatório. O local de partida da viagem em coordenadas de latitude/longitude.
dropoff_point Opcional. O local de desembarque da viagem em coordenadas de latitude/longitude. O campo é obrigatório se trip_types contiver TripType.SHARED.
pickup_radius_meters Obrigatório. O raio em metros da área de pesquisa de veículos a partir do ponto de coleta.
order_by Obrigatório. Ordene os veículos por uma das seguintes opções:
  • PICKUP_POINT_ETA, a HEC do veículo no ponto de encontro.
  • PICKUP_POINT_DISTANCE, a distância entre o veículo e o ponto de embarque.
  • DROPOFF_POINT_ETA, a ETA do veículo para concluir a viagem no ponto de desembarque.
  • PICKUP_POINT_STRAIGHT_DISTANCE, a distância em linha reta (não na rota) entre o veículo e o ponto de embarque.
contagem Obrigatório. O número máximo de veículos a serem retornados, de 1 a 50.
filtrar Opcional. Uma consulta de filtro a ser aplicada ao pesquisar veículos.
maximum_staleness Opcional. Restringe a pesquisa apenas aos veículos que enviaram atualizações de localização para o Fleet Engine dentro da duração especificada. Se esse campo não for definido, o servidor usará cinco minutos como valor padrão.

Consulte a documentação de referência para ver o conjunto completo de campos SearchVehicleRequest.

Cenários de SearchVehiclesRequest

Esta seção mostra exemplos de como construir um SearchVehiclesRequest.

Por exemplo, suponha que um cliente queira ser buscado no RestaurantX e você tenha quatro veículos:

  • Veículo 1: a 3.500 m do RestaurantX.
  • Veículo 2: a 100 m do RestaurantX com uma viagem ativa com retirada e desembarque nos locais A e B.
  • Veículo 3: a 200 m do RestaurantX com uma entrega restante muito distante.
  • Veículo 4: a 1.000 m do RestaurantX.

A seguir, mostramos várias solicitações pelo veículo que elas retornam.

Retorna o veículo 4

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

Retorna os veículos 3 e 4

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

Retorna os veículos 2, 3 e 4

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

Campos de SearchVehiclesResponse

Um SearchVehiclesResponse consiste em uma lista de entidades VehicleMatch, classificadas pelo atributo order_by especificado no SearchVehiclesRequest. Cada entidade VehicleMatch tem os seguintes campos:

Campo Descrição
veículo O objeto Vehicle, incluindo os atributos vehicle_id e Vehicle.
vehicle_pickup_eta A estimativa de chegada do veículo no local de partida se a viagem fosse atribuída a ele agora.
vehicle_pickup_distance_meter A distância em metros entre o veículo e o local de partida da nova viagem.
vehicle_pickup_straight_line_distance_meter A distância em linha reta em metros entre o veículo e o local de partida da nova viagem.
vehicle_dropoff_eta A ETA do veículo no local de desembarque se a viagem fosse atribuída ao veículo agora.
vehicle_trips_waypoints Uma lista dos pontos de parada restantes, incluindo os pontos de embarque e desembarque, para as viagens ativas atribuídas ao veículo.
vehicle_match_type O tipo de viagem do veículo: EXCLUSIVE, BACK_TO_BACK, CARPOOL ou CARPOOL_BACK_TO_BACK.

Para uma lista completa de campos VehicleMatch, consulte:

Usar consultas de filtro

SearchVehicles e ListVehicles oferecem suporte à filtragem de atributos do veículo usando uma consulta de filtro.

As consultas de filtro SÓ aceitam filtragem em atributos personalizados para veículos e não podem ser usadas em outros campos. Quando usado em uma pesquisa que inclui outros critérios de campo, como minimum_capacity ou vehicle_types, a consulta de filtro funciona como uma cláusula AND.

Por exemplo, se você pesquisar um veículo com capacidade mínima de 6 pessoas e filtrar um attributes, como aceita animais de estimação, seus critérios vão retornar apenas os veículos que aceitam animais de estimação e podem transportar pelo menos 6 passageiros.

Para ver exemplos de sintaxe de consulta de filtro, consulte AIP-160. Para detalhes sobre como criar atributos de veículo, consulte o Campo de atributos do veículo no guia Atualizar campos do veículo.

Exemplo de SearchVehicles

O exemplo a seguir mostra como usar a API SearchVehicles com a biblioteca gRPC Java.

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.

A seguir