List delivery vehicles

This document describes how to list delivery vehicles.

Environments and limitations

You can list delivery vehicles from a server or browser environment. The Driver SDK does not support listing delivery vehicles.

Listing delivery vehicles requests broad access to delivery vehicles and is intended only for trusted users. Use Delivery Fleet Reader or Fleet Engine Delivery Admin tokens when making list delivery vehicles requests.

Listed delivery vehicles have the following fields redacted due to their impact on response size:

  • CurrentRouteSegment
  • RemainingVehicleJourneySegments

Usage

You can list vehicles by attribute filters and viewport bounds. If you specify no filter or viewport, the response includes all delivery vehicles.

List with attributes filters

You can list delivery vehicles by filter using their attributes property. For example, to query an attribute with key my_key and value my_value, use attributes.my_key = my_value. To query for multiple attributes, join queries using the logical AND and OR operators as in attributes.key1 = value1 AND attributes.key2 = value2. See AIP-160 for a full description of filter query syntax. If you combine filters with viewport bounds, the filter acts as an AND operator to the viewport bound. See Vehicle attributes filter queries for details.

List with viewport bounds

You can filter listed delivery vehicles by location using the viewport request parameter. The viewport request parameter defines viewports using two bounding coordinates: a high (northeast) and low (southwest) latitude and longitude coordinates pair. Requests are rejected if they contain a high latitude that is geographically lower than a low latitude.

List responses

Delivery vehicle lists are paginated by default using a reasonable page size. If you specify a page size, the request returns only the number of vehicles specified by the limit, or fewer. If the requested page size exceeds an internal maximum value, then the internal maximum is used. The default and maximum page sizes are both 100 vehicles.

A delivery vehicles list can include a token for reading the next page of results. A page token is only present in a response when more pages of delivery vehicles are available for retrieval. To retrieve the next page of tasks, use the page token with a request that is otherwise identical to the previous request.

List vehicles examples

You can use the Java gRPC library or REST to list delivery vehicles in a particular region with a certain attribute. A successful response can still be empty. When that happens, it means that no vehicles with the specified attribute exist in the specified viewport.

Java


  static final String PROJECT_ID = "my-delivery-co-gcp-project";

  DeliveryServiceBlockingStub deliveryService =
    DeliveryServiceGrpc.newBlockingStub(channel);

  // Tasks request
  String parent = "providers/" + PROJECT_ID;
  ListDeliveryVehiclesRequest listDeliveryVehiclesRequest =
    ListDeliveryVehiclesRequest.newBuilder()  // No need for the header
        .setParent(parent)
        .setViewport(
              Viewport.newBuilder()
                .setHigh(LatLng.newBuilder()
                    .setLatitude(37.45)
                    .setLongitude(-122.06)
                    .build())
                .setLow(LatLng.newBuilder()
                    .setLatitude(37.41)
                    .setLongitude(-122.11)
                    .build())
        .setFilter("attributes.my_key = my_value")
        .build();

  try {
    ListDeliveryVehiclesResponse listDeliveryVehiclesResponse =
        deliveryService.listDeliveryVehicles(listDeliveryVehiclesRequest);
  } catch (StatusRuntimeException e) {
    Status s = e.getStatus();
    switch (s.getCode()) {
        case NOT_FOUND:
            break;

        case PERMISSION_DENIED:
            break;
    }
    return;
  }

REST

  # HTTP request
  html GET https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles


  # Request with a filter
  # Request sets JWT, PROJECT_ID, and VEHICLE_ID in the local environment
  curl -H "Authorization: Bearer ${JWT}" \
    "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles?filter=attributes.my_key%20%3D%20my_value%20&viewport.high.latitude=37.45&viewport.high.longitude=-122.06&viewport.low.latitude=37.41&viewport.low.longitude=-122.11"

If the lookup is successful, the response body contains data with the following structure:

  // JSON representation
  {
    "deliveryVehicles": [
      {
        object (DeliveryVehicle)
      }
    ],
    "nextPageToken": string,
    "totalSize": integer
  }

What's next