Ricerca di conducenti nelle vicinanze

Come parte della tua Soluzione On-demand Rides and Deliveries, la funzionalità Pianificazione del percorso e spedizione ti consente di trovare conducenti nelle vicinanze grazie a un'API SearchVehicles.

L'API SearchVehicles ti consente di trovare conducenti disponibili nelle vicinanze nella tua app per consumatori Soluzione Trasporto passeggeri on demand più adatti a un'attività come una corsa o una richiesta di consegna. L'API SearchVehicles restituisce un elenco classificato di conducenti che corrispondono agli attributi delle attività con gli attributi dei veicoli del tuo parco veicoli.

Gli attributi delle attività possono includere:

  • Luoghi di prelievo e destinazione
  • Tipi di veicolo e di viaggio richiesti
  • Capacità richiesta
  • Altri attributi di corrispondenza obbligatori

Gli attributi dei veicoli possono includere:

  • L'ultima posizione nota di un veicolo
  • Lo stato, il tipo o la capacità del veicolo
  • Altri attributi personalizzati

Il ranking viene ordinato in base all'orario di arrivo stimato, alla distanza o alla distanza in linea retta dal punto di partenza.

Tieni presente che, per utilizzare l'API SearchVehicles, devi disporre dei privilegi Super User o Consumer SDK User del servizio Fleet Engine. Per maggiori informazioni, consulta Autenticazione e autorizzazione.

Utilizzo dell'API SearchVeicolis

Per utilizzare l'API SearchVehicles:

  • Crea un SearchVehiclesRequest in base all'attività da assegnare.
  • Chiama l'API SearchVehicles (vehicleService.searchVehicles) con la richiesta creata.
  • Elabora SearchVehicleResponse restituito dall'API.

Campi SearchVeicolisRequest

Utilizza i seguenti campi degli attributi obbligatori per creare un SearchVehiclesRequest:

Campo Descrizione
parent Obbligatorio. Deve essere nel formato provider/{provider}. Il provider deve essere l'ID progetto (ad esempio sample-cloud-project) del progetto Google Cloud di cui fa parte l'account di servizio che effettua questa chiamata.
vehicle_types Obbligatorio. Tipi di veicoli richiesti: AUTO, TWO_WHEELER, TAXI, TRUCK, BICYCLE o PEDESTRIAN.
trip_types Obbligatorio. ESCLUSIVO (una corsa attiva alla volta per autista) o CONDIVISI (una o più corse alla volta per autista).
minimum_capacity Obbligatorio. La capacità minima rimanente del veicolo per una nuova attività, per passeggeri o consegne.
pickup_point Obbligatorio. Il punto di partenza dell'attività nelle coordinate di latitudine/longitudine.
dropoff_point Campo facoltativo. Il punto di consegna dell'attività nelle coordinate di latitudine/longitudine. Il campo è obbligatorio se trip_types contiene TripType.SHARED.
pickup_radius_meters Obbligatorio. Il raggio in metri dell'area di ricerca dei veicoli dal punto di ritiro.
order_by Obbligatorio. Ordina i veicoli in base a uno dei seguenti criteri:
  • PICKUP_POINT_ETA, l'orario di arrivo stimato del veicolo al punto di ritiro.
  • PICKUP_POINT_DISTANCE, la distanza tra il veicolo e il punto di partenza.
  • DROPOFF_POINT_ETA, l'orario di arrivo stimato del veicolo per completare la corsa al punto di partenza.
  • PICKUP_POINT_STRAIGHT_DISTANCE, la distanza in linea retta (non lungo il percorso) tra il veicolo e il punto di partenza.
count Obbligatorio. Il numero massimo di veicoli da restituire da 1 a 50.

Consulta la documentazione di riferimento per visualizzare l'insieme completo di SearchVehicleRequestfields.

Esempi di richieste di veicoli per la ricerca

Questa sezione mostra esempi di come creare un SearchVehiclesRequest.

Ad esempio, supponiamo che tu debba assegnare un'attività di ritiro al RestaurantX e quattro veicoli:

  • Veicolo 1, a 3500 m di distanza da RestaurantX.
  • Veicolo 2, a 100 m da RestaurantX, con una corsa attiva con servizio di prelievo e ritiro presso le sedi A e B.
  • Il veicolo 3, a 200 m di distanza da RestaurantX, ha una fermata ancora molto lontana.
  • Veicolo 4, a 1000 m di distanza da RestaurantX.

Il seguente SearchVehiclesRequest restituisce il Veicolo 4:

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

Il seguente SearchVehiclesRequest restituisce il Veicolo 3 e 4:

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

Il seguente SearchVehiclesRequest restituisce il Veicolo 2, 3 e 4:

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

Campi SearchVeicolisResponse

Un SearchVehiclesResponse è composto da un elenco di entità VehicleMatch, classificate in base all'attributo order_by specificato in SearchVehiclesRequest. Ogni entità VehicleMatch ha i seguenti campi:

Campo Descrizione
Veicolo L'oggetto Vehicle, inclusi gli attributi traffic_id e Vehicle.
vehicle_pickup_eta L'orario di arrivo stimato del veicolo nel luogo di prelievo della nuova attività. Questo è l'orario di arrivo stimato in auto.
vehicle_pickup_distance_meter La distanza in metri tra il veicolo e il punto di prelievo della nuova attività.
vehicle_pickup_straight_line_distance_meter La distanza in linea retta in metri tra il veicolo e il punto di partenza della nuova attività.
vehicle_dropoff_eta Il timestamp dell'orario di arrivo stimato del veicolo nel luogo di prelievo della nuova attività. Tieni presente che l'orario di arrivo stimato è l'orario di arrivo stimato in auto.
vehicle_trips_waypoints Un elenco di tappe rimanenti, inclusi i punti di prelievo e destinazione, per le corse attive attualmente assegnate al veicolo.
vehicle_match_type Il tipo di corsa del veicolo, EXCLUSIVE, BACK_TO_BACK, CARPOOL o CARPOOL_BACK_TO_BACK.

Esempio SearchVeicoli

L'esempio seguente mostra come utilizzare l'API SearchVehicles:

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.