Method: providers.vehicles.search

Returns a list of vehicles that match the request options.

HTTP request

POST https://fleetengine.googleapis.com/v1/{parent=providers/*}/vehicles:search

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
parent

string

Required. Must be in the format providers/{provider}. The provider must be the Project ID (for example, sample-cloud-project) of the Google Cloud Project of which the service account making this call is a member.

Request body

The request body contains data with the following structure:

JSON representation 
{
  "header": {
    object (RequestHeader)
  },
  "pickupPoint": {
    object (TerminalLocation)
  },
  "dropoffPoint": {
    object (TerminalLocation)
  },
  "pickupRadiusMeters": integer,
  "count": integer,
  "minimumCapacity": integer,
  "tripTypes": [
    enum (TripType)
  ],
  "maximumStaleness": string,
  "vehicleTypes": [
    {
      object (VehicleType)
    }
  ],
  "requiredAttributes": [
    {
      object (VehicleAttribute)
    }
  ],
  "requiredOneOfAttributes": [
    {
      object (VehicleAttributeList)
    }
  ],
  "requiredOneOfAttributeSets": [
    {
      object (VehicleAttributeList)
    }
  ],
  "orderBy": enum (VehicleMatchOrder),
  "includeBackToBack": boolean,
  "tripId": string,
  "currentTripsPresent": enum (CurrentTripsPresent),
  "filter": string
}
Fields
header

object (RequestHeader)

The standard Fleet Engine request header.
pickupPoint

object (TerminalLocation)

Required. The pickup point to search near.
dropoffPoint

object (TerminalLocation)

The customer's intended dropoff location. The field is required if tripTypes contains TripType.SHARED.
pickupRadiusMeters

integer

Required. Defines the vehicle search radius around the pickup point. Only vehicles within the search radius will be returned. Value must be between 400 and 10000 meters (inclusive).
count

integer

Required. Specifies the maximum number of vehicles to return. The value must be between 1 and 50 (inclusive).
minimumCapacity

integer

Required. Specifies the number of passengers being considered for a trip. The value must be greater than or equal to one. The driver is not considered in the capacity value.
tripTypes[]

enum (TripType)

Required. Represents the type of proposed trip. Must include exactly one type. UNKNOWN_TRIP_TYPE is not allowed. Restricts the search to only those vehicles that can support that trip type.
maximumStaleness

string (Duration format)

Restricts the search to only those vehicles that have sent location updates to Fleet Engine within the specified duration. Stationary vehicles still transmitting their locations are not considered stale. If this field is not set, the server uses five minutes as the default value.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".
vehicleTypes[]

object (VehicleType)

Required. Restricts the search to vehicles with one of the specified types. At least one vehicle type must be specified. VehicleTypes with a category of UNKNOWN are not allowed.
requiredAttributes[]

object (VehicleAttribute)

Callers can form complex logical operations using any combination of the requiredAttributes, requiredOneOfAttributes, and requiredOneOfAttributeSets fields.

requiredAttributes is a list; requiredOneOfAttributes uses a message which allows a list of lists. In combination, the two fields allow the composition of this expression:

(requiredAttributes[0] AND requiredAttributes[1] AND ...)
AND
(requiredOneOfAttributes[0][0] OR requiredOneOfAttributes[0][1] OR
...)
AND
(requiredOneOfAttributes[1][0] OR requiredOneOfAttributes[1][1] OR
...)

Restricts the search to only those vehicles with the specified attributes. This field is a conjunction/AND operation. A max of 50 requiredAttributes is allowed. This matches the maximum number of attributes allowed on a vehicle.
requiredOneOfAttributes[]

object (VehicleAttributeList)

Restricts the search to only those vehicles with at least one of the specified attributes in each VehicleAttributeList. Within each list, a vehicle must match at least one of the attributes. This field is an inclusive disjunction/OR operation in each VehicleAttributeList and a conjunction/AND operation across the collection of VehicleAttributeList.
requiredOneOfAttributeSets[]

object (VehicleAttributeList)

requiredOneOfAttributeSets provides additional functionality.

Similar to requiredOneOfAttributes, requiredOneOfAttributeSets uses a message which allows a list of lists, allowing expressions such as this one:

(requiredAttributes[0] AND requiredAttributes[1] AND ...)
AND
(
  (requiredOneOfAttributeSets[0][0] AND
  requiredOneOfAttributeSets[0][1] AND
  ...)
  OR
  (requiredOneOfAttributeSets[1][0] AND
  requiredOneOfAttributeSets[1][1] AND
  ...)
)

Restricts the search to only those vehicles with all the attributes in a VehicleAttributeList. Within each list, a vehicle must match all of the attributes. This field is a conjunction/AND operation in each VehicleAttributeList and inclusive disjunction/OR operation across the collection of VehicleAttributeList.
orderBy

enum (VehicleMatchOrder)

Required. Specifies the desired ordering criterion for results.
includeBackToBack

boolean

This indicates if vehicles with a single active trip are eligible for this search. This field is only used when currentTripsPresent is unspecified. When currentTripsPresent is unspecified and this field is false, vehicles with assigned trips are excluded from the search results. When currentTripsPresent is unspecified and this field is true, search results can include vehicles with one active trip that has a status of ENROUTE_TO_DROPOFF. When currentTripsPresent is specified, this field cannot be set to true.

The default value is false.
tripId

string

Indicates the trip associated with this SearchVehicleRequest.
currentTripsPresent

enum (CurrentTripsPresent)

This indicates if vehicles with active trips are eligible for this search. This must be set to something other than CURRENT_TRIPS_PRESENT_UNSPECIFIED if tripType includes SHARED.
filter

string

Optional. A filter query to apply when searching vehicles. See http://aip.dev/160 for examples of the filter syntax.

This field is designed to replace the requiredAttributes, requiredOneOfAttributes, and required_one_of_attributes_sets fields. If a non-empty value is specified here, the following fields must be empty: requiredAttributes, requiredOneOfAttributes, and required_one_of_attributes_sets.

This filter functions as an AND clause with other constraints, such as minimumCapacity or vehicleTypes.

Note that the only queries supported are on vehicle attributes (for example, attributes.<key> = <value> or attributes.<key1> = <value1> AND attributes.<key2> = <value2>). The maximum number of restrictions allowed in a filter query is 50.

Also, all attributes are stored as strings, so the only supported comparisons against attributes are string comparisons. In order to compare against number or boolean values, the values must be explicitly quoted to be treated as strings (for example, attributes.<key> = "10" or attributes.<key> = "true").

Response body

vehicles.search response message.

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

JSON representation 
{
  "matches": [
    {
      object (VehicleMatch)
    }
  ]
}
Fields
matches[]

object (VehicleMatch)

List of vehicles that match the SearchVehiclesRequest criteria, ordered according to SearchVehiclesRequest.order_by field.

VehicleAttributeList

A list-of-lists datatype for vehicle attributes.

JSON representation 
{
  "attributes": [
    {
      object (VehicleAttribute)
    }
  ]
}
Fields
attributes[]

object (VehicleAttribute)

A list of attributes in this collection.

VehicleMatchOrder

Specifies the order of the vehicle matches in the response.

Enums
UNKNOWN_VEHICLE_MATCH_ORDER Default, used for unspecified or unrecognized vehicle matches order.
PICKUP_POINT_ETA Ascending order by vehicle driving time to the pickup point.
PICKUP_POINT_DISTANCE Ascending order by vehicle driving distance to the pickup point.
DROPOFF_POINT_ETA Ascending order by vehicle driving time to the dropoff point. This order can only be used if the dropoff point is specified in the request.
PICKUP_POINT_STRAIGHT_DISTANCE Ascending order by straight-line distance from the vehicle's last reported location to the pickup point.
COST Ascending order by the configured match cost. Match cost is defined as a weighted calculation between straight-line distance and ETA. Weights are set with default values and can be modified per customer. Please contact Google support if these weights need to be modified for your project.

CurrentTripsPresent

Specifies the types of restrictions on a vehicle's current trips.

Enums
CURRENT_TRIPS_PRESENT_UNSPECIFIED The availability of vehicles with trips present is governed by the includeBackToBack field.
NONE Vehicles without trips can appear in search results. When this value is used, includeBackToBack cannot be true.
ANY Vehicles with at most 5 current trips and 10 waypoints are included in the search results. When this value is used, includeBackToBack cannot be true.

VehicleMatch

Contains the vehicle and related estimates for a vehicle that match the points of active trips for the vehicle SearchVehiclesRequest.

JSON representation 
{
  "vehicle": {
    object (Vehicle)
  },
  "vehiclePickupEta": string,
  "vehiclePickupDistanceMeters": integer,
  "vehiclePickupStraightLineDistanceMeters": integer,
  "vehicleDropoffEta": string,
  "vehiclePickupToDropoffDistanceMeters": integer,
  "tripType": enum (TripType),
  "vehicleTripsWaypoints": [
    {
      object (Waypoint)
    }
  ],
  "vehicleMatchType": enum (VehicleMatchType),
  "requestedOrderedBy": enum (VehicleMatchOrder),
  "orderedBy": enum (VehicleMatchOrder)
}
Fields
vehicle

object (Vehicle)

Required. A vehicle that matches the request.
vehiclePickupEta

string (Timestamp format)

The vehicle's driving ETA to the pickup point specified in the request. An empty value indicates a failure in calculating ETA for the vehicle. If SearchVehiclesRequest.include_back_to_back was true and this vehicle has an active trip, vehiclePickupEta includes the time required to complete the current active trip.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
vehiclePickupDistanceMeters

integer

The distance from the Vehicle's current location to the pickup point specified in the request, including any intermediate pickup or dropoff points for existing trips. This distance comprises the calculated driving (route) distance, plus the straight line distance between the navigation end point and the requested pickup point. (The distance between the navigation end point and the requested pickup point is typically small.) An empty value indicates an error in calculating the distance.
vehiclePickupStraightLineDistanceMeters

integer

Required. The straight-line distance between the vehicle and the pickup point specified in the request.
vehicleDropoffEta

string (Timestamp format)

The complete vehicle's driving ETA to the drop off point specified in the request. The ETA includes stopping at any waypoints before the dropoffPoint specified in the request. The value will only be populated when a drop off point is specified in the request. An empty value indicates an error calculating the ETA.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
vehiclePickupToDropoffDistanceMeters

integer

The vehicle's driving distance (in meters) from the pickup point to the drop off point specified in the request. The distance is only between the two points and does not include the vehicle location or any other points that must be visited before the vehicle visits either the pickup point or dropoff point. The value will only be populated when a dropoffPoint is specified in the request. An empty value indicates a failure in calculating the distance from the pickup to drop off point specified in the request.
tripType

enum (TripType)

Required. The trip type of the request that was used to calculate the ETA to the pickup point.
vehicleTripsWaypoints[]

object (Waypoint)

The ordered list of waypoints used to calculate the ETA. The list includes vehicle location, the pickup points of active trips for the vehicle, and the pickup points provided in the request. An empty list indicates a failure in calculating ETA for the vehicle.
vehicleMatchType

enum (VehicleMatchType)

Type of the vehicle match.
requestedOrderedBy

enum (VehicleMatchOrder)

The order requested for sorting vehicle matches.
orderedBy

enum (VehicleMatchOrder)

The actual order that was used for this vehicle. Normally this will match the 'orderBy' field from the request; however, in certain circumstances such as an internal server error, a different method may be used (such as PICKUP_POINT_STRAIGHT_DISTANCE).

Waypoint

Describes intermediate points along a route for a VehicleMatch in a SearchVehiclesResponse. This concept is represented as a TripWaypoint in all other endpoints.

JSON representation 
{
  "latLng": {
    object (LatLng)
  },
  "eta": string
}
Fields
latLng

object (LatLng)

The location of this waypoint.
eta

string (Timestamp format)

The estimated time that the vehicle will arrive at this waypoint.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

VehicleMatchType

Type of vehicle match.

Enums
UNKNOWN Unknown vehicle match type
EXCLUSIVE The vehicle currently has no trip assigned to it and can proceed to the pickup point.
BACK_TO_BACK The vehicle is currently assigned to a trip, but can proceed to the pickup point after completing the in-progress trip. ETA and distance calculations take the existing trip into account.
CARPOOL The vehicle has sufficient capacity for a shared ride.
CARPOOL_BACK_TO_BACK The vehicle will finish its current, active trip before proceeding to the pickup point. ETA and distance calculations take the existing trip into account.