path: root/third_party/googleapis/google/maps/fleetengine/v1/vehicle_api.proto

// Copyright 2022 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package maps.fleetengine.v1;

import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/api/routing.proto";
import "google/maps/fleetengine/v1/fleetengine.proto";
import "google/maps/fleetengine/v1/header.proto";
import "google/maps/fleetengine/v1/vehicles.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/timestamp.proto";
import "google/protobuf/wrappers.proto";
import "google/type/latlng.proto";

option go_package = "google.golang.org/genproto/googleapis/maps/fleetengine/v1;fleetengine";
option java_multiple_files = true;
option java_outer_classname = "VehicleApi";
option java_package = "google.maps.fleetengine.v1";
option objc_class_prefix = "CFE";

// Vehicle management service.
service VehicleService {
  option (google.api.default_host) = "fleetengine.googleapis.com";

  // Instantiates a new vehicle associated with an on-demand rideshare or
  // deliveries provider. Each `Vehicle` must have a unique vehicle ID.
  //
  // The following `Vehicle` fields are required when creating a `Vehicle`:
  //
  // * `vehicleState`
  // * `supportedTripTypes`
  // * `maximumCapacity`
  // * `vehicleType`
  //
  // The following `Vehicle` fields are ignored when creating a `Vehicle`:
  //
  // * `name`
  // * `currentTrips`
  // * `availableCapacity`
  // * `current_route_segment`
  // * `current_route_segment_end_point`
  // * `current_route_segment_version`
  // * `current_route_segment_traffic`
  // * `route`
  // * `waypoints`
  // * `waypoints_version`
  // * `remaining_distance_meters`
  // * `remaining_time_seconds`
  // * `eta_to_next_waypoint`
  // * `navigation_status`
  //
  // All other fields are optional and used if provided.
  rpc CreateVehicle(CreateVehicleRequest) returns (Vehicle) {
    option (google.api.http) = {
      post: "/v1/{parent=providers/*}/vehicles"
      body: "vehicle"
    };
    option (google.api.routing) = {
      routing_parameters {
        field: "parent"
        path_template: "{provider_id=providers/*}"
      }
    };
  }

  // Returns a vehicle from the Fleet Engine.
  rpc GetVehicle(GetVehicleRequest) returns (Vehicle) {
    option (google.api.http) = {
      get: "/v1/{name=providers/*/vehicles/*}"
    };
    option (google.api.routing) = {
      routing_parameters {
        field: "name"
        path_template: "{provider_id=providers/*}"
      }
    };
  }

  // Writes updated vehicle data to the Fleet Engine.
  //
  // When updating a `Vehicle`, the following fields cannot be updated since
  // they are managed by the server:
  //
  // * `currentTrips`
  // * `availableCapacity`
  // * `current_route_segment_version`
  // * `waypoints_version`
  //
  // The vehicle `name` also cannot be updated.
  //
  // If the `attributes` field is updated, **all** the vehicle's attributes are
  // replaced with the attributes provided in the request. If you want to update
  // only some attributes, see the `UpdateVehicleAttributes` method. Likewise,
  // the `waypoints` field can be updated, but must contain all the waypoints
  // currently on the vehicle, and no other waypoints.
  rpc UpdateVehicle(UpdateVehicleRequest) returns (Vehicle) {
    option (google.api.http) = {
      put: "/v1/{name=providers/*/vehicles/*}"
      body: "vehicle"
    };
    option (google.api.routing) = {
      routing_parameters {
        field: "name"
        path_template: "{provider_id=providers/*}"
      }
    };
  }

  // Deprecated: Use the `UpdateVehicle` method instead.
  // UpdateVehicleLocation updates the location of the vehicle.
  rpc UpdateVehicleLocation(UpdateVehicleLocationRequest) returns (VehicleLocation) {
    option deprecated = true;
    option (google.api.http) = {
      put: "/v1/{name=providers/*/vehicles/*}:updateLocation"
      body: "*"
    };
    option (google.api.routing) = {
      routing_parameters {
        field: "name"
        path_template: "{provider_id=providers/*}"
      }
    };
  }

  // Partially updates a vehicle's attributes.
  // Only the attributes mentioned in the request will be updated, other
  // attributes will NOT be altered. Note: this is different in `UpdateVehicle`,
  // where the whole `attributes` field will be replaced by the one in
  // `UpdateVehicleRequest`, attributes not in the request would be removed.
  rpc UpdateVehicleAttributes(UpdateVehicleAttributesRequest) returns (UpdateVehicleAttributesResponse) {
    option (google.api.http) = {
      post: "/v1/{name=providers/*/vehicles/*}:updateAttributes"
      body: "*"
    };
    option (google.api.routing) = {
      routing_parameters {
        field: "name"
        path_template: "{provider_id=providers/*}"
      }
    };
  }

  // Returns a paginated list of vehicles associated with
  // a provider that match the request options.
  rpc ListVehicles(ListVehiclesRequest) returns (ListVehiclesResponse) {
    option (google.api.http) = {
      get: "/v1/{parent=providers/*}/vehicles"
    };
    option (google.api.routing) = {
      routing_parameters {
        field: "parent"
        path_template: "{provider_id=providers/*}"
      }
    };
  }

  // Returns a list of vehicles that match the request options.
  rpc SearchVehicles(SearchVehiclesRequest) returns (SearchVehiclesResponse) {
    option (google.api.http) = {
      post: "/v1/{parent=providers/*}/vehicles:search"
      body: "*"
    };
    option (google.api.routing) = {
      routing_parameters {
        field: "parent"
        path_template: "{provider_id=providers/*}"
      }
    };
  }

  // Returns a list of vehicles that match the request
  // options, but the vehicle locations will be somewhat altered for privacy.
  // This method does not support the `SearchVehicleRequest.order_by` field.
  // Vehicle matches in the response will be in order of distance from the
  // pickup point.  Only the `vehicle` and `trip_type` fields will be populated.
  rpc SearchFuzzedVehicles(SearchVehiclesRequest) returns (SearchVehiclesResponse) {
    option (google.api.http) = {
      post: "/v1/{parent=providers/*}/vehicles:searchFuzzed"
      body: "*"
    };
    option (google.api.routing) = {
      routing_parameters {
        field: "parent"
        path_template: "{provider_id=providers/*}"
      }
    };
  }
}

// `CreateVehicle` request message.
message CreateVehicleRequest {
  // The standard Fleet Engine request header.
  RequestHeader header = 1;

  // 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.
  string parent = 3 [(google.api.field_behavior) = REQUIRED];

  // Required. Unique Vehicle ID.
  // Subject to the following restrictions:
  //
  // * Must be a valid Unicode string.
  // * Limited to a maximum length of 64 characters.
  // * Normalized according to [Unicode Normalization Form C]
  // (http://www.unicode.org/reports/tr15/).
  // * May not contain any of the following ASCII characters: '/', ':', '?',
  // ',', or '#'.
  string vehicle_id = 4 [(google.api.field_behavior) = REQUIRED];

  // Required. The Vehicle entity to create. When creating a Vehicle, the following
  // fields are required:
  //
  // * `vehicleState`
  // * `supportedTripTypes`
  // * `maximumCapacity`
  // * `vehicleType`
  //
  // When creating a Vehicle, the following fields are ignored:
  //
  // * `name`
  // * `currentTrips`
  // * `availableCapacity`
  // * `current_route_segment`
  // * `current_route_segment_end_point`
  // * `current_route_segment_version`
  // * `current_route_segment_traffic`
  // * `route`
  // * `waypoints`
  // * `waypoints_version`
  // * `remaining_distance_meters`
  // * `remaining_time_seconds`
  // * `eta_to_next_waypoint`
  // * `navigation_status`
  //
  // All other fields are optional and used if provided.
  Vehicle vehicle = 5 [(google.api.field_behavior) = REQUIRED];
}

// `GetVehicle` request message.
message GetVehicleRequest {
  // The standard Fleet Engine request header.
  RequestHeader header = 1;

  // Required. Must be in the format
  // `providers/{provider}/vehicles/{vehicle}`.
  // 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.
  string name = 3 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "fleetengine.googleapis.com/Vehicle"
    }
  ];

  // Indicates the minimum timestamp (exclusive) for which
  // `Vehicle.current_route_segment` is retrieved.
  // If the route is unchanged since this timestamp, the `current_route_segment`
  // field is not set in the response. If a minimum is unspecified, the
  // `current_route_segment` is always retrieved.
  google.protobuf.Timestamp current_route_segment_version = 4;

  // Indicates the minimum timestamp (exclusive) for which `Vehicle.waypoints`
  // data is retrieved. If the waypoints are unchanged since this timestamp, the
  // `vehicle.waypoints` data is not set in the response. If this field is
  // unspecified, `vehicle.waypoints` is always retrieved.
  google.protobuf.Timestamp waypoints_version = 5;
}

// `UpdateVehicle request message.
message UpdateVehicleRequest {
  // The standard Fleet Engine request header.
  RequestHeader header = 1;

  // Required. Must be in the format
  // `providers/{provider}/vehicles/{vehicle}`.
  // 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.
  string name = 3 [(google.api.field_behavior) = REQUIRED];

  // Required. The `Vehicle` entity values to apply.  When updating a `Vehicle`,
  // the following fields may not be updated as they are managed by the
  // server.
  //
  // * `current_trips`
  // * `available_capacity`
  // * `current_route_segment_version`
  // * `waypoints_version`
  //
  // Furthermore, the vehicle `name` cannot be updated.
  //
  // If the `attributes` field is updated, **all** the vehicle's attributes are
  // replaced with the attributes provided in the request. If you want to update
  // only some attributes, see the `UpdateVehicleAttributes` method. Likewise,
  // the `waypoints` field can be updated, but must contain all the waypoints.
  // currently on the vehicle, and no other waypoints.
  Vehicle vehicle = 4 [(google.api.field_behavior) = REQUIRED];

  // Required. A field mask indicating which fields of the `Vehicle` to update.
  // At least one field name must be provided.
  google.protobuf.FieldMask update_mask = 5 [(google.api.field_behavior) = REQUIRED];
}

// `UpdateVehicleLocation` request message.
message UpdateVehicleLocationRequest {
  option deprecated = true;

  // The standard Fleet Engine request header.
  RequestHeader header = 1;

  // Required. Must be in the format
  // `providers/{provider}/vehicles/{vehicle}`.
  // 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.
  string name = 3 [(google.api.field_behavior) = REQUIRED];

  // Required. The vehicle's most recent location.  The `location` and `update_time`
  // subfields are required.
  VehicleLocation current_location = 4 [(google.api.field_behavior) = REQUIRED];

  // Set the vehicle's state to either `ONLINE` or `OFFLINE`.
  // If set to `UNKNOWN_VEHICLE_STATE`, the vehicle's state will not be altered.
  VehicleState current_state = 5;
}

// `UpdateVehicleAttributes` request message.
message UpdateVehicleAttributesRequest {
  // The standard Fleet Engine request header.
  RequestHeader header = 1;

  // Required. Must be in the format `providers/{provider}/vehicles/{vehicle}`.
  // 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.
  string name = 3 [(google.api.field_behavior) = REQUIRED];

  // Required. The vehicle attributes to update. Unmentioned attributes will not be
  // altered or removed.
  repeated VehicleAttribute attributes = 4 [(google.api.field_behavior) = REQUIRED];
}

// `UpdateVehicleAttributes` response message.
message UpdateVehicleAttributesResponse {
  // Required. The updated full list of vehicle attributes, including new,
  // altered and untouched attributes.
  repeated VehicleAttribute attributes = 1 [(google.api.field_behavior) = REQUIRED];
}

// `SearchVehicles` request message.
message SearchVehiclesRequest {
  // Specifies the order of the vehicle matches in the response.
  enum VehicleMatchOrder {
    // Default, used for unspecified or unrecognized vehicle matches order.
    UNKNOWN_VEHICLE_MATCH_ORDER = 0;

    // Ascending order by vehicle driving time to the pickup point.
    PICKUP_POINT_ETA = 1;

    // Ascending order by vehicle driving distance to the pickup point.
    PICKUP_POINT_DISTANCE = 2;

    // 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.
    DROPOFF_POINT_ETA = 3;

    // Ascending order by straight-line distance from the vehicle's last
    // reported location to the pickup point.
    PICKUP_POINT_STRAIGHT_DISTANCE = 4;

    // Ascending order by the configured match cost.
    COST = 5;
  }

  // Specifies the types of restrictions on a vehicle's current trips.
  enum CurrentTripsPresent {
    // Only vehicles without trips can appear in search results.
    // A validation exception is thrown if `include_back_to_back` is true. See
    // the `include_back_to_back` flag for more details.
    CURRENT_TRIPS_PRESENT_UNSPECIFIED = 0;

    // Vehicles without trips can appear in search results.
    // A validation exception is thrown if `include_back_to_back` is true.
    NONE = 1;

    // Vehicles with at most 5 current trips and 10 waypoints are included
    // in the search results.
    // A validation exception is thrown if `include_back_to_back` is true.
    ANY = 2;
  }

  // The standard Fleet Engine request header.
  RequestHeader header = 1;

  // 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.
  string parent = 3 [(google.api.field_behavior) = REQUIRED];

  // Required. The pickup point to search near.
  TerminalLocation pickup_point = 4 [(google.api.field_behavior) = REQUIRED];

  // The customer's intended dropoff location. The field is required if
  // `trip_types` contains `TripType.SHARED`.
  TerminalLocation dropoff_point = 5;

  // 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).
  int32 pickup_radius_meters = 6 [(google.api.field_behavior) = REQUIRED];

  // Required. Specifies the maximum number of vehicles to return. The value
  // must be between 1 and 50 (inclusive).
  int32 count = 7 [(google.api.field_behavior) = REQUIRED];

  // 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.
  int32 minimum_capacity = 8 [(google.api.field_behavior) = REQUIRED];

  // Required. Represents the type of proposed trip. Eligible vehicles are those
  // that can support at least one of the specified trip type.
  //
  // `EXCLUSIVE` and `SHARED` may not be included together.
  // `SHARED` is not supported when `current_trips_present` is
  // `CURRENT_TRIPS_PRESENT_UNSPECIFIED`.
  repeated TripType trip_types = 9 [(google.api.field_behavior) = REQUIRED];

  // Restricts the search to only those vehicles that have updated their
  // locations within the specified duration. If this field is not
  // set, the server uses five minutes as the default value.
  google.protobuf.Duration maximum_staleness = 10;

  // Required. Restricts the search to vehicles with one of the specified types.
  // At least one vehicle type must be specified.
  repeated Vehicle.VehicleType vehicle_types = 14 [(google.api.field_behavior) = REQUIRED];

  // Callers can form complex logical operations using any combination of the
  // `required_attributes`, `required_one_of_attributes`, and
  // `required_one_of_attribute_sets` fields.
  //
  // `required_attributes` is a list; `required_one_of_attributes` uses a
  // message which allows a list of lists. In combination, the two fields allow
  // the composition of this expression:
  //
  // ```
  // (required_attributes[0] AND required_attributes[1] AND ...)
  // AND
  // (required_one_of_attributes[0][0] OR required_one_of_attributes[0][1] OR
  // ...)
  // AND
  // (required_one_of_attributes[1][0] OR required_one_of_attributes[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 required_attributes
  // is allowed. This matches the maximum number of attributes allowed on a
  // vehicle.
  repeated VehicleAttribute required_attributes = 12;

  // 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`.
  repeated VehicleAttributeList required_one_of_attributes = 15;

  // `required_one_of_attribute_sets` provides additional functionality.
  //
  // Similar to `required_one_of_attributes`, `required_one_of_attribute_sets`
  // uses a message which allows a list of lists, allowing expressions such as
  // this one:
  //
  // ```
  // (required_attributes[0] AND required_attributes[1] AND ...)
  // AND
  // (required_one_of_attribute_sets[0][0] AND
  // required_one_of_attribute_sets[0][1] AND
  // ...)
  // OR
  // (required_one_of_attribute_sets[1][0] AND
  // required_one_of_attribute_sets[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`.
  repeated VehicleAttributeList required_one_of_attribute_sets = 20;

  // Required. Specifies the desired ordering criterion for results.
  VehicleMatchOrder order_by = 13 [(google.api.field_behavior) = REQUIRED];

  // Indicates if a vehicle with a single active trip is eligible for another
  // match. If `false`, vehicles with assigned trips are excluded from the
  // search results. If `true`, search results include vehicles with
  // `TripStatus` of `ENROUTE_TO_DROPOFF`.
  //
  // This field is only considered if a single `trip_type` of `EXCLUSIVE` is
  // specified.
  //
  // The default value is `false`.
  bool include_back_to_back = 18;

  // Indicates the trip associated with this `SearchVehicleRequest`.
  string trip_id = 19;

  // Restricts vehicles from appearing in the search results based on
  // their current trips.
  //
  // When current_trips_present is `NONE` or `ANY`, `trip_types` can be either
  // `EXCLUSIVE` or `SHARED`, but not both.
  CurrentTripsPresent current_trips_present = 21;
}

// `SearchVehicles` response message.
message SearchVehiclesResponse {
  // List of vehicles that match the `SearchVehiclesRequest` criteria, ordered
  // according to `SearchVehiclesRequest.order_by` field.
  repeated VehicleMatch matches = 1;
}

// `ListVehicles` request message.
message ListVehiclesRequest {
  // The standard Fleet Engine request header.
  RequestHeader header = 12;

  // 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.
  string parent = 1 [(google.api.field_behavior) = REQUIRED];

  // The maximum number of vehicles to return.
  // Default value: 100.
  int32 page_size = 3;

  // The `next_page_token` value returned from a previous call to
  // `ListVehicles`. Functionality is undefined if the filter criteria of this
  // request don't match the criteria in the request that produced this
  // `page_token`.
  string page_token = 4;

  // Specifies the required minimum capacity of the vehicle. All vehicles
  // returned will have a `maximum_capacity` greater than or equal to this
  // value. If set, must be greater or equal to 0.
  google.protobuf.Int32Value minimum_capacity = 6;

  // Restrict the response to vehicles that support at least
  // one of the specified trip types.
  repeated TripType trip_types = 7;

  // Restrict the response to vehicles that have updated
  // their locations within the specified duration back from now.
  // If present, must be a valid positive duration.
  google.protobuf.Duration maximum_staleness = 8;

  // Required. Restrict the response to vehicles with one of the specified type
  // categories.
  repeated Vehicle.VehicleType.Category vehicle_type_categories = 9 [(google.api.field_behavior) = REQUIRED];

  // Callers can form complex logical operations using any combination of the
  // `required_attributes`, `required_one_of_attributes`, and
  // `required_one_of_attribute_sets` fields.
  //
  // `required_attributes` is a list; `required_one_of_attributes` uses a
  // message which allows a list of lists. In combination, the two fields allow
  // the composition of this expression:
  //
  // ```
  // (required_attributes[0] AND required_attributes[1] AND ...)
  // AND
  // (required_one_of_attributes[0][0] OR required_one_of_attributes[0][1] OR
  // ...)
  // AND
  // (required_one_of_attributes[1][0] OR required_one_of_attributes[1][1] OR
  // ...)
  // ```
  //
  // Restrict the response to vehicles with the specified attributes. This field
  // is a conjunction/AND operation. A max of 50 required_attributes is allowed.
  // This matches the maximum number of attributes allowed on a vehicle. Each
  // repeated string should be of the format "key:value".
  repeated string required_attributes = 10;

  // Restrict the response to 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`. Each repeated string should be of the
  // format "key1:value1|key2:value2|key3:value3".
  repeated string required_one_of_attributes = 13;

  // `required_one_of_attribute_sets` provides additional functionality.
  //
  // Similar to `required_one_of_attributes`, `required_one_of_attribute_sets`
  // uses a message which allows a list of lists, allowing expressions such as
  // this one:
  //
  // ```
  // (required_attributes[0] AND required_attributes[1] AND ...)
  // AND
  // (required_one_of_attributes[0][0] AND required_one_of_attributes[0][1] AND
  // ...)
  // OR
  // (required_one_of_attributes[1][0] AND required_one_of_attributes[1][1] AND
  // ...)
  // ```
  //
  // Restrict the response to vehicles that match 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`. Each repeated string should be of the
  // format "key1:value1|key2:value2|key3:value3".
  repeated string required_one_of_attribute_sets = 15;

  // Restrict the response to vehicles that have this vehicle state.
  VehicleState vehicle_state = 11;

  // Only return the vehicles with current trip(s).
  bool on_trip_only = 14;
}

// `ListVehicles` response message.
message ListVehiclesResponse {
  // Vehicles matching the criteria in the request.
  // The maximum number of vehicles returned is determined by the `page_size`
  // field in the request.
  repeated Vehicle vehicles = 1;

  // Token to retrieve the next page of vehicles, or empty if there are no
  // more vehicles that meet the request criteria.
  string next_page_token = 2;

  // Required. Total number of vehicles matching the request criteria across all pages.
  int64 total_size = 3 [(google.api.field_behavior) = REQUIRED];
}

// Describes intermediate points along a route.
message Waypoint {
  // The location of this waypoint.
  google.type.LatLng lat_lng = 1;

  // The estimated time that the vehicle will arrive at this waypoint.
  google.protobuf.Timestamp eta = 2;
}

// Contains the vehicle and related estimates for a vehicle that match the
// points of active trips for the vehicle `SearchVehiclesRequest`.
message VehicleMatch {
  // Type of vehicle match.
  enum VehicleMatchType {
    // Unknown vehicle match type
    UNKNOWN = 0;

    // The vehicle currently has no trip assigned to it and can proceed to the
    // pickup point.
    EXCLUSIVE = 1;

    // 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.
    BACK_TO_BACK = 2;

    // The vehicle has sufficient capacity for a shared ride.
    CARPOOL = 3;

    // The vehicle will finish its current, active trip before proceeding to the
    // pickup point.  ETA and distance calculations take the existing trip into
    // account.
    CARPOOL_BACK_TO_BACK = 4;
  }

  // Required. A vehicle that matches the request.
  Vehicle vehicle = 1 [(google.api.field_behavior) = REQUIRED];

  // 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, `vehicle_pickup_eta` includes the time
  // required to complete the current active trip.
  google.protobuf.Timestamp vehicle_pickup_eta = 2;

  // 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.
  google.protobuf.Int32Value vehicle_pickup_distance_meters = 3;

  // Required. The straight-line distance between the vehicle and the pickup point
  // specified in the request.
  google.protobuf.Int32Value vehicle_pickup_straight_line_distance_meters = 11 [(google.api.field_behavior) = REQUIRED];

  // The complete vehicle's driving ETA to the drop off point specified in the
  // request. The ETA includes stopping at any waypoints before the
  // `dropoff_point` 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.
  google.protobuf.Timestamp vehicle_dropoff_eta = 4;

  // 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
  // `dropoff_point` 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.
  google.protobuf.Int32Value vehicle_pickup_to_dropoff_distance_meters = 5;

  // Required. The trip type of the request that was used to calculate the ETA
  // to the pickup point.
  TripType trip_type = 6 [(google.api.field_behavior) = REQUIRED];

  // The ordered list of waypoints used to calculate the ETA. The list
  // includes vehicle location, the pickup/drop off points of active
  // trips for the vehicle, and the pickup/drop off points provided in the
  // request. An empty list indicates a failure in calculating ETA for the
  // vehicle.
  repeated Waypoint vehicle_trips_waypoints = 7;

  // Type of the vehicle match.
  VehicleMatchType vehicle_match_type = 8;

  // The order requested for sorting vehicle matches.
  SearchVehiclesRequest.VehicleMatchOrder requested_ordered_by = 9;

  // The actual order that was used for this vehicle. Normally this
  // will match the 'order_by' 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`).
  SearchVehiclesRequest.VehicleMatchOrder ordered_by = 10;
}

// A list-of-lists datatype for vehicle attributes.
message VehicleAttributeList {
  // A list of attributes in this collection.
  repeated VehicleAttribute attributes = 1;
}