diff --git a/google/maps/fleetengine/v1/BUILD.bazel b/google/maps/fleetengine/v1/BUILD.bazel index d3774b02db..be381bbc77 100644 --- a/google/maps/fleetengine/v1/BUILD.bazel +++ b/google/maps/fleetengine/v1/BUILD.bazel @@ -1,5 +1,6 @@ # This file was automatically generated by BuildFileGenerator # https://github.com/googleapis/rules_gapic/tree/master/bazel + # Most of the manual changes to this file will be overwritten. # It's **only** allowed to change the following rule attribute values: # - names of *_gapic_assembly_* rules @@ -7,6 +8,7 @@ # * extra_protoc_parameters # * extra_protoc_file_parameters # The complete list of preserved parameters can be found in the source code. + # This is an API workspace, having public visibility by default makes perfect sense. package(default_visibility = ["//visibility:public"]) @@ -21,6 +23,7 @@ proto_library( srcs = [ "fleetengine.proto", "header.proto", + "traffic.proto", "trip_api.proto", "trips.proto", "vehicle_api.proto", @@ -32,7 +35,6 @@ proto_library( "//google/api:field_behavior_proto", "//google/api:resource_proto", "//google/type:latlng_proto", - "@com_google_protobuf//:any_proto", "@com_google_protobuf//:duration_proto", "@com_google_protobuf//:empty_proto", "@com_google_protobuf//:field_mask_proto", @@ -75,12 +77,15 @@ java_grpc_library( java_gapic_library( name = "fleetengine_java_gapic", srcs = [":fleetengine_proto_with_info"], + gapic_yaml = None, grpc_service_config = "fleetengine_grpc_service_config.json", + service_yaml = "fleetengine.yaml", test_deps = [ ":fleetengine_java_grpc", ], deps = [ ":fleetengine_java_proto", + "//google/api:api_java_proto", ], ) @@ -134,7 +139,7 @@ go_gapic_library( metadata = True, service_yaml = "fleetengine.yaml", deps = [ - ":fleetengine_go_proto", + ":fleetengine_go_proto", "@io_bazel_rules_go//proto/wkt:duration_go_proto", ], ) diff --git a/google/maps/fleetengine/v1/fleetengine.proto b/google/maps/fleetengine/v1/fleetengine.proto index eaa6cde047..2110677172 100644 --- a/google/maps/fleetengine/v1/fleetengine.proto +++ b/google/maps/fleetengine/v1/fleetengine.proto @@ -17,7 +17,7 @@ syntax = "proto3"; package maps.fleetengine.v1; import "google/api/field_behavior.proto"; -import "google/protobuf/any.proto"; +import "google/maps/fleetengine/v1/traffic.proto"; import "google/protobuf/duration.proto"; import "google/protobuf/timestamp.proto"; import "google/protobuf/wrappers.proto"; @@ -55,10 +55,10 @@ message TerminalLocation { // Deprecated. string access_point_id = 3 [deprecated = true]; - // Deprecated. Use vehicle.waypoint instead. + // Deprecated. string trip_id = 4 [deprecated = true]; - // Deprecated. Vehicle.waypoint will have this data. + // Deprecated: `Vehicle.waypoint` will have this data. WaypointType terminal_location_type = 5 [deprecated = true]; } @@ -79,64 +79,33 @@ message TripWaypoint { // current waypoint. repeated google.type.LatLng path_to_waypoint = 4; + // The path calculated by the server from the previous waypoint to the current + // waypoint. Decoding is not yet supported. + string encoded_path_to_waypoint = 5; + + // The traffic conditions along the path to this waypoint. + // Note that traffic is only available for Geo Enterprise Rides and Deliveries + // Solution customers. + ConsumableTrafficPolyline traffic_to_waypoint = 10; + // The path distance calculated by Fleet Engine from the previous waypoint to - // the current waypoint. - // If the current waypoint is the first waypoint in the list (Vehicle.waypoint - // or Trip.remaining_waypoints), then the starting point is the vehicle's - // location recorded at the time this TripWaypoint was added to the list. + // the current waypoint. If the waypoint is the first waypoint in the list + // (e.g., `Vehicle.waypoints[0]` or `Trip.remaining_waypoints[0]`), then the + // value of this field is undefined. google.protobuf.Int32Value distance_meters = 6; // The arrival time to this waypoint calculated by Fleet Engine. google.protobuf.Timestamp eta = 7; - // The travel time from previous waypoint to this point. - // If the current waypoint is the first waypoint in the list (Vehicle.waypoint - // or Trip.remaining_waypoints), then the starting point is the vehicle's - // location recorded at the time that this waypoint was added to the list. - // This field is filled only when returning Trip/Vehicle data. + // The travel time from previous waypoint to this point. If the waypoint is + // the first waypoint in the list (e.g., `Vehicle.waypoints[0]` or + // `Trip.remaining_waypoints[0]`), then this value indicates the remaining + // time to the waypoint. google.protobuf.Duration duration = 8; } -// The 'Status' defines a FleetEngine custom logical error mode. -message Status { - // The canonical error code. - enum Code { - // Unspecified status, not a valid value to set. - UNSPECIFIED = 0; - - // Internal server error. Usually expect the client to retry in this case. - FAILURE = 1; - - // There is no possible route. Client should not retry. - ROUTE_NOT_POSSIBLE = 2; - } - - // The error code. It is not possible to have a value as 0 if it is explicitly - // set by the server. - Code code = 1; - - // Detailed error message. - string message = 2; - - // A list of messages that carry the error details. There is a common set of - // message types for APIs to use. - repeated google.protobuf.Any details = 3; -} - -// A full, human-readable address for the entity containing this message. -message FormattedAddress { - // The lines of text that describe the address. - // At least one line must be present. - repeated string lines = 1; -} - -// Address of a place. -message Address { - // A full, human-readable address for this place. - FormattedAddress formatted_address = 1; -} - -// Describes a vehicle attribute as a key-value pair. +// Describes a vehicle attribute as a key-value pair. The "key:value" string +// length cannot exceed 256 characters. message VehicleAttribute { // The attribute's key. Keys may not contain the colon character (:). string key = 1; @@ -148,72 +117,68 @@ message VehicleAttribute { // The location, speed, and heading of a vehicle at a point in time. message VehicleLocation { // The location of the vehicle. - // When it is sent to FleetEngine, the vehicle's location is a GPS location. + // When it is sent to Fleet Engine, the vehicle's location is a GPS location. // When you receive it in a response, the vehicle's location can be either a - // GPS location or a supplemental location. The source is specified in the - // field 'location_sensor'. + // GPS location, a supplemental location, or some other estimated location. + // The source is specified in `location_sensor`. google.type.LatLng location = 1; - // Deprecated. Use latlng_accuracy instead. + // Deprecated: Use `latlng_accuracy` instead. google.protobuf.DoubleValue horizontal_accuracy = 8 [deprecated = true]; - // Accuracy of horizontal measurements (lat/lng) in meters as a radius. + // Accuracy of `location` in meters as a radius. google.protobuf.DoubleValue latlng_accuracy = 22; // Direction the vehicle is moving in degrees. 0 represents North. // The valid range is [0,360). google.protobuf.Int32Value heading = 2; - // Deprecated. Use heading_accuracy instead. + // Deprecated: Use `heading_accuracy` instead. google.protobuf.DoubleValue bearing_accuracy = 10 [deprecated = true]; - // Accuracy of heading (bearing) in degrees. + // Accuracy of `heading` in degrees. google.protobuf.DoubleValue heading_accuracy = 23; // Altitude in meters above WGS84. google.protobuf.DoubleValue altitude = 5; - // Deprecated. Use altitude_accurarcy instead. + // Deprecated: Use `altitude_accuracy` instead. google.protobuf.DoubleValue vertical_accuracy = 9 [deprecated = true]; - // Accuracy of altitude measurement in meters. + // Accuracy of `altitude` in meters. google.protobuf.DoubleValue altitude_accuracy = 24; // Speed of the vehicle in kilometers per hour. - // Deprecated. Use speed instead. + // Deprecated: Use `speed` instead. google.protobuf.Int32Value speed_kmph = 3 [deprecated = true]; // Speed of the vehicle in meters/second google.protobuf.DoubleValue speed = 6; - // Accuracy of speed in meters/second. + // Accuracy of `speed` in meters/second. google.protobuf.DoubleValue speed_accuracy = 7; - // The time when the location was recorded. + // The time when `location` was reported by the sensor. google.protobuf.Timestamp update_time = 4; - // Output only. The time when the server receives the location information, filled by - // FleetEngine. + // Output only. The time when the server received the location information. google.protobuf.Timestamp server_time = 13 [(google.api.field_behavior) = OUTPUT_ONLY]; - // Provider of location data (for example, "gps"). + // Provider of location data (for example, `GPS`). LocationSensor location_sensor = 11; - // Whether the vehicle location given by "location" field is snapped to a road - // closest to the location given by "raw_location". - // Driver SDK 1.15.1/2.1.1 and up will always set this field. - // Unset value will be treated as true. + // Whether `location` is snapped to a road. google.protobuf.BoolValue is_road_snapped = 27; - // Input only. Indicates whether the GPS sensor is enabled. + // Input only. Indicates whether the GPS sensor is enabled on the mobile device. google.protobuf.BoolValue is_gps_sensor_enabled = 12 [(google.api.field_behavior) = INPUT_ONLY]; - // Input only. Time (in seconds) since this location sample was first sent to the server. + // Input only. Time (in seconds) since this location was first sent to the server. // This will be zero for the first update. If the time is unknown // (for example, when the app restarts), this value resets to zero. google.protobuf.Int32Value time_since_update = 14 [(google.api.field_behavior) = INPUT_ONLY]; - // Input only. Number of additional attempts to send the current location to the server. + // Input only. Number of additional attempts to send this location to the server. // If this value is zero, then it is not stale. google.protobuf.Int32Value num_stale_updates = 15 [(google.api.field_behavior) = INPUT_ONLY]; @@ -226,7 +191,7 @@ message VehicleLocation { // Input only. Source of the raw location. LocationSensor raw_location_sensor = 28 [(google.api.field_behavior) = INPUT_ONLY]; - // Input only. Accuracy of the raw location (lat/lng) as a radius, measured in meters. + // Input only. Accuracy of `raw_location` as a radius, in meters. google.protobuf.DoubleValue raw_location_accuracy = 25 [(google.api.field_behavior) = INPUT_ONLY]; // Input only. Supplemental location provided by the integrating app, such as the location @@ -239,11 +204,10 @@ message VehicleLocation { // Input only. Source of the supplemental location. LocationSensor supplemental_location_sensor = 20 [(google.api.field_behavior) = INPUT_ONLY]; - // Input only. Accuracy of supplemental location (lat/lng) as a radius, measured in - // meters. + // Input only. Accuracy of `supplemental_location` as a radius, in meters. google.protobuf.DoubleValue supplemental_location_accuracy = 21 [(google.api.field_behavior) = INPUT_ONLY]; - // Deprecated, use is_road_snapped instead. + // Deprecated: Use `is_road_snapped` instead. bool road_snapped = 26 [deprecated = true]; } @@ -261,13 +225,13 @@ enum TripType { // The type of waypoint. enum WaypointType { - // Default, unknown waypoint type + // Unknown or unspecified waypoint type. UNKNOWN_WAYPOINT_TYPE = 0; - // Waypoints for picking up customers or merchandise. + // Waypoints for picking up riders or items. PICKUP_WAYPOINT_TYPE = 1; - // Waypoints for dropping off customers or merchandise. + // Waypoints for dropping off riders or items. DROP_OFF_WAYPOINT_TYPE = 2; // Waypoints for intermediate destinations in a multi-destination trip. @@ -276,10 +240,10 @@ enum WaypointType { // The type of polyline format. enum PolylineFormatType { - // Unspecified format type. + // The format is unspecified or unknown. UNKNOWN_FORMAT_TYPE = 0; - // Repeated LatLng. + // A list of `google.type.LatLng`. LAT_LNG_LIST_TYPE = 1; // A polyline encoded with a polyline compression algorithm. Decoding is not @@ -287,43 +251,42 @@ enum PolylineFormatType { ENCODED_POLYLINE_TYPE = 2; } -// A set of values that specify the vehicle's navigation status. +// The vehicle's navigation status. enum NavigationStatus { // Unspecified navigation status. UNKNOWN_NAVIGATION_STATUS = 0; - // The Driver app's navigation is in FREE_NAV mode. + // The Driver app's navigation is in `FREE_NAV` mode. NO_GUIDANCE = 1; - // Turn-by-turn navigation starts and the Driver app navigation enters - // GUIDED_NAV mode showing the green header, route, and destination marker. + // Turn-by-turn navigation is available and the Driver app navigation has + // entered `GUIDED_NAV` mode. ENROUTE_TO_DESTINATION = 2; - // Vehicle has gone off the suggested route. + // The vehicle has gone off the suggested route. OFF_ROUTE = 3; - // The vehicle is within 50m of the destination and onArrival was - // automatically triggered. + // The vehicle is within approximately 50m of the destination. ARRIVED_AT_DESTINATION = 4; } -// Possible location providers. +// The sensor or methodology used to determine the location. enum LocationSensor { - // Undefined sensor. + // The sensor is unspecified or unknown. UNKNOWN_SENSOR = 0; - // Sensors: (GPS, AGPS). + // GPS or Assisted GPS. GPS = 1; - // Sensors: (AGPS, CellID, WiFi MACID). + // Assisted GPS, cell tower ID, or WiFi access point. NETWORK = 2; - // Sensors: (CellID, WiFi MACID). + // Cell tower ID or WiFi access point. PASSIVE = 3; - // GMM's road snapped (gmfc) location. + // A location signal snapped to the best road position. ROAD_SNAPPED_LOCATION_PROVIDER = 4; - // Unspecified, but generated by the Fused Location Provider. + // The fused location provider in Google Play services. FUSED_LOCATION_PROVIDER = 100; } diff --git a/google/maps/fleetengine/v1/fleetengine.yaml b/google/maps/fleetengine/v1/fleetengine.yaml index 88002415ec..fffce93deb 100644 --- a/google/maps/fleetengine/v1/fleetengine.yaml +++ b/google/maps/fleetengine/v1/fleetengine.yaml @@ -8,7 +8,9 @@ apis: - name: maps.fleetengine.v1.VehicleService documentation: - summary: Services for ridesharing providers. + summary: |- + Enables Fleet Engine for access to the On Demand Rides and Deliveries and + Last Mile Fleet Solution APIs. backend: rules: @@ -16,3 +18,5 @@ backend: deadline: 10.0 - selector: 'maps.fleetengine.v1.VehicleService.*' deadline: 10.0 + - selector: maps.fleetengine.v1.VehicleService.UpdateVehicleLocation + deadline: 3.0 diff --git a/google/maps/fleetengine/v1/header.proto b/google/maps/fleetengine/v1/header.proto index 4a1d352c75..c20f907325 100644 --- a/google/maps/fleetengine/v1/header.proto +++ b/google/maps/fleetengine/v1/header.proto @@ -26,21 +26,78 @@ option objc_class_prefix = "CFE"; // A RequestHeader contains fields common to all Fleet Engine RPC requests. message RequestHeader { - // The language requested. The external form of Google International - // Identifiers Initiative (III) LanguageCode objects. If none is specified, - // return a name in any language, with a preference for English if such a - // name exists. + // Possible types of SDK. + enum SdkType { + // The default value. This value is used if the `sdk_type` is omitted. + SDK_TYPE_UNSPECIFIED = 0; + + // The calling SDK is Consumer. + CONSUMER = 1; + + // The calling SDK is Driver. + DRIVER = 2; + + // The calling SDK is JavaScript. + JAVASCRIPT = 3; + } + + // The platform of the calling SDK. + enum Platform { + // The default value. This value is used if the platform is omitted. + PLATFORM_UNSPECIFIED = 0; + + // The request is coming from Android. + ANDROID = 1; + + // The request is coming from iOS. + IOS = 2; + + // The request is coming from the web. + WEB = 3; + } + + // The BCP-47 language code, such as en-US or sr-Latn. For more information, + // see http://www.unicode.org/reports/tr35/#Unicode_locale_identifier. If none + // is specified, the response may be in any language, with a preference for + // English if such a name exists. Field value example: `en-US`. string language_code = 1; // Required. CLDR region code of the region where the request originates. + // Field value example: `US`. string region_code = 2 [(google.api.field_behavior) = REQUIRED]; // Version of the calling SDK, if applicable. + // The version format is "major.minor.patch", example: `1.1.2`. string sdk_version = 3; // Version of the operating system on which the calling SDK is running. + // Field value examples: `4.4.1`, `12.1`. string os_version = 4; // Model of the device on which the calling SDK is running. + // Field value examples: `iPhone12,1`, `SM-G920F`. string device_model = 5; + + // The type of SDK sending the request. + SdkType sdk_type = 6; + + // Version of the MapSDK which the calling SDK depends on, if applicable. + // The version format is "major.minor.patch", example: `5.2.1`. + string maps_sdk_version = 7; + + // Version of the NavSDK which the calling SDK depends on, if applicable. + // The version format is "major.minor.patch", example: `2.1.0`. + string nav_sdk_version = 8; + + // Platform of the calling SDK. + Platform platform = 9; + + // Manufacturer of the Android device from the calling SDK, only applicable + // for the Android SDKs. + // Field value example: `Samsung`. + string manufacturer = 10; + + // Android API level of the calling SDK, only applicable for the Android SDKs. + // Field value example: `23`. + int32 android_api_level = 11; } diff --git a/google/maps/fleetengine/v1/traffic.proto b/google/maps/fleetengine/v1/traffic.proto new file mode 100644 index 0000000000..11768bc93e --- /dev/null +++ b/google/maps/fleetengine/v1/traffic.proto @@ -0,0 +1,67 @@ +// Copyright 2021 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; + +option go_package = "google.golang.org/genproto/googleapis/maps/fleetengine/v1;fleetengine"; +option java_multiple_files = true; +option java_outer_classname = "TrafficProto"; +option java_package = "google.maps.fleetengine.v1"; +option objc_class_prefix = "CFE"; + +// Traffic density indicator on a contiguous segment of a path. Given a path +// with points P_0, P_1, ... , P_N (zero-based index), the SpeedReadingInterval +// defines an interval and describes its traffic using the following categories. +message SpeedReadingInterval { + // The classification of polyline speed based on traffic data. + enum Speed { + // Default value. This value is unused. + SPEED_UNSPECIFIED = 0; + + // Normal speed, no slowdown is detected. + NORMAL = 1; + + // Slowdown detected, but no traffic jam formed. + SLOW = 2; + + // Traffic jam detected. + TRAFFIC_JAM = 3; + } + + // The starting index of this interval in the path. + // In JSON, when the index is 0, the field will appear to be unpopulated. + int32 start_polyline_point_index = 1; + + // The ending index of this interval in the path. + // In JSON, when the index is 0, the field will appear to be unpopulated. + int32 end_polyline_point_index = 2; + + // Traffic speed in this interval. + Speed speed = 3; +} + +// Traffic density along a Vehicle's path. +message ConsumableTrafficPolyline { + // Traffic speed along the path from the previous waypoint to the current + // waypoint. + repeated SpeedReadingInterval speed_reading_interval = 1; + + // The path the driver is taking from the previous waypoint to the current + // waypoint. This path has landmarks in it so clients can show traffic markers + // along the path (see `speed_reading_interval`). Decoding is not yet + // supported. + string encoded_path_to_waypoint = 2; +} diff --git a/google/maps/fleetengine/v1/trip_api.proto b/google/maps/fleetengine/v1/trip_api.proto index db07e30433..413246e3ee 100644 --- a/google/maps/fleetengine/v1/trip_api.proto +++ b/google/maps/fleetengine/v1/trip_api.proto @@ -83,8 +83,8 @@ message CreateTripRequest { // 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) + // 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 [ @@ -94,28 +94,34 @@ message CreateTripRequest { } ]; - // Required. Unique Trip ID; must be unique per provider. The actual - // format and value is opaque to the Fleet Engine and is determined - // by the provider. + // Required. Unique Trip ID; must be unique per provider. + // Subject to the following normalization and restrictions: + // + // 1. IDs must be valid Unicode strings. + // 2. IDs are limited to a maximum length of 64 characters. + // 3. IDs will be normalized according to Unicode Normalization Form C + // (http://www.unicode.org/reports/tr15/). + // 4. IDs may not contain any of the following ASCII characters: '/', ':', + // '\\', '?', or '#'. string trip_id = 5 [(google.api.field_behavior) = REQUIRED]; // Required. Trip entity to create. // // When creating a Trip, the following fields are required: // - // * trip_type - // * pickup_point + // * `trip_type` + // * `pickup_point` // // The following fields are used if you provide them: // - // * number_of_passengers - // * vehicle_id - // * dropoff_point - // * intermediate_destinations + // * `number_of_passengers` + // * `vehicle_id` + // * `dropoff_point` + // * `intermediate_destinations` // - // Only EXCLUSIVE trips support multiple destinations. + // Only `EXCLUSIVE` trips support multiple destinations. // - // When vehicle_id is set for a shared trip, you must supply + // When `vehicle_id` is set for a shared trip, you must supply // the list of `Trip.vehicle_waypoints` to specify the order of the remaining // waypoints for the vehicle, otherwise the waypoint order will be // undetermined. @@ -128,7 +134,7 @@ message CreateTripRequest { // waypoints must not interleave with any other trips. // // The `trip_id`, `waypoint_type` and `location` fields are used, and all - // other TripWaypoint fields in vehicle_waypoints are ignored. + // other TripWaypoint fields in `vehicle_waypoints` are ignored. // // All other Trip fields are ignored. Trip trip = 4 [(google.api.field_behavior) = REQUIRED]; @@ -139,8 +145,8 @@ message GetTripRequest { // The standard Fleet Engine request header. RequestHeader header = 1; - // Required. Must be in the format "providers/{provider}/trips/{trip}". - // The provider must be the Project ID (for example, sample-cloud-project) + // Required. Must be in the format `providers/{provider}/trips/{trip}`. + // 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 [ @@ -153,22 +159,38 @@ message GetTripRequest { // The subset of Trip fields that should be returned and their interpretation. TripView view = 11; - // Indicates the minimum timestamp (exclusive) for which Trip.route or - // Trip.current_route_segment data is retrieved. If route data is unchanged - // since this timestamp, the route field is not set in the response. If a - // minimum is unspecified, the route data is always retrieved. + // Indicates the minimum timestamp (exclusive) for which `Trip.route` or + // `Trip.current_route_segment` data are retrieved. If route data are + // unchanged since this timestamp, the route field is not set in the response. + // If a minimum is unspecified, the route data are always retrieved. google.protobuf.Timestamp current_route_segment_version = 6; // Indicates the minimum timestamp (exclusive) for which - // Trip.remaining_waypoints are retrieved. If they are unchanged since this - // timestamp, the remaining_waypoints are not set in the response. If this - // field is unspecified, remaining_waypoints is always retrieved. + // `Trip.remaining_waypoints` are retrieved. If they are unchanged since this + // timestamp, the `remaining_waypoints` are not set in the response. If this + // field is unspecified, `remaining_waypoints` is always retrieved. google.protobuf.Timestamp remaining_waypoints_version = 7; - // The returned current route format, LAT_LNG_LIST_TYPE (in Trip.route), or - // ENCODED_POLYLINE_TYPE (in Trip.current_route_segment). - // The default is LAT_LNG_LIST_TYPE. + // The returned current route format, `LAT_LNG_LIST_TYPE` (in `Trip.route`), + // or `ENCODED_POLYLINE_TYPE` (in `Trip.current_route_segment`). The default + // is `LAT_LNG_LIST_TYPE`. PolylineFormatType route_format_type = 8; + + // Indicates the minimum timestamp (exclusive) for which + // `Trip.current_route_segment_traffic` is retrieved. If traffic data are + // unchanged since this timestamp, the `current_route_segment_traffic` field + // is not set in the response. If a minimum is unspecified, the traffic data + // are always retrieved. Note that traffic is only available for On-Demand + // Rides and Deliveries Solution customers. + google.protobuf.Timestamp current_route_segment_traffic_version = 9; + + // Indicates the minimum timestamp (exclusive) for which + // `Trip.remaining_waypoints.traffic_to_waypoint` and + // `Trip.remaining_waypoints.path_to_waypoint` data are retrieved. If data are + // unchanged since this timestamp, the fields above are + // not set in the response. If `remaining_waypoints_route_version` is + // unspecified, traffic and path are always retrieved. + google.protobuf.Timestamp remaining_waypoints_route_version = 10; } // ReportBillableTrip request message. @@ -176,7 +198,7 @@ message ReportBillableTripRequest { // Selector for different solution types of a reported trip. enum SolutionType { // The default value. For backwards-compatibility, the API will use - // ON_DEMAND_RIDESHARING_AND_DELIVERIES by default which is the first + // `ON_DEMAND_RIDESHARING_AND_DELIVERIES` by default which is the first // supported solution type. SOLUTION_TYPE_UNSPECIFIED = 0; @@ -185,9 +207,9 @@ message ReportBillableTripRequest { } // Required. Must be in the format - // "providers/{provider}/billableTrips/{billable_trip}". 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 + // `providers/{provider}/billableTrips/{billable_trip}`. 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 = 2 [(google.api.field_behavior) = REQUIRED]; @@ -200,12 +222,12 @@ message ReportBillableTripRequest { // The identifiers that are directly related to the trip being reported. These // are usually IDs (for example, session IDs) of pre-booking operations done - // before the trip ID is available. The number of related_ids is + // before the trip ID is available. The number of `related_ids` is // limited to 50. repeated string related_ids = 6; // The type of GMP product solution (for example, - // ON_DEMAND_RIDESHARING_AND_DELIVERIES) used for the reported trip. + // `ON_DEMAND_RIDESHARING_AND_DELIVERIES`) used for the reported trip. SolutionType solution_type = 7; } @@ -216,7 +238,7 @@ message UpdateTripRequest { // Required. Must be in the format // `providers/{provider}/trips/{trip}`. The provider must - // be the Project ID (for example, sample-consumer-project) of the Google + // be the Project ID (for example, `sample-consumer-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]; @@ -225,17 +247,23 @@ message UpdateTripRequest { // The following fields are maintained by the Fleet Engine. Do not update // them using Trip.update. // - // * current_route_segment - // * current_route_segment_version - // * eta_to_next_waypoint - // * intermediate_destinations_version - // * last_location - // * name - // * number_of_passengers - // * remaining_distance_meters - // * remaining_time_to_first_waypoint - // * remaining_waypoints - // * remaining_waypoints_version + // * `current_route_segment` + // * `current_route_segment_end_point` + // * `current_route_segment_traffic` + // * `current_route_segment_traffic_version` + // * `current_route_segment_version` + // * `dropoff_time` + // * `eta_to_next_waypoint` + // * `intermediate_destinations_version` + // * `last_location` + // * `name` + // * `number_of_passengers` + // * `pickup_time` + // * `remaining_distance_meters` + // * `remaining_time_to_first_waypoint` + // * `remaining_waypoints` + // * `remaining_waypoints_version` + // * `route` // // When you update the `Trip.vehicle_id` for a shared trip, you must supply // the list of `Trip.vehicle_waypoints` to specify the order of the remaining @@ -248,7 +276,7 @@ message UpdateTripRequest { // destinations come before the drop-off point. An `EXCLUSIVE` trip's // waypoints must not interleave with any other trips. // The `trip_id`, `waypoint_type` and `location` fields are used, and all - // other TripWaypoint fields in vehicle_waypoints are ignored. + // other TripWaypoint fields in `vehicle_waypoints` are ignored. // // To avoid a race condition for trips with multiple destinations, you // should provide `Trip.intermediate_destinations_version` when updating @@ -258,7 +286,7 @@ message UpdateTripRequest { Trip trip = 4 [(google.api.field_behavior) = REQUIRED]; // Required. The field mask indicating which fields in Trip to update. - // The update_mask must contain at least one field. + // The `update_mask` must contain at least one field. google.protobuf.FieldMask update_mask = 5 [(google.api.field_behavior) = REQUIRED]; } @@ -267,8 +295,8 @@ message SearchTripsRequest { // The standard Fleet Engine request header. RequestHeader header = 1; - // Required. Must be in the format "providers/*" - // The provider must be the Project ID (for example, sample-cloud-project) + // 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]; @@ -276,10 +304,10 @@ message SearchTripsRequest { // The vehicle associated with the trips in the request. If unspecified, the // returned trips do not contain: // - // * current_route_segment - // * remaining_waypoints - // * remaining_distance_meters - // * eta_to_first_waypoint + // * `current_route_segment` + // * `remaining_waypoints` + // * `remaining_distance_meters` + // * `eta_to_first_waypoint` string vehicle_id = 4; // If set to true, only Trips that influence the drivers route @@ -295,7 +323,7 @@ message SearchTripsRequest { string page_token = 7; // If specified, returns the trips that have not been updated after - // the time (current - minimum_staleness). + // the time `(current - minimum_staleness)`. google.protobuf.Duration minimum_staleness = 8; } diff --git a/google/maps/fleetengine/v1/trips.proto b/google/maps/fleetengine/v1/trips.proto index e9e9d101ea..f42ed651a1 100644 --- a/google/maps/fleetengine/v1/trips.proto +++ b/google/maps/fleetengine/v1/trips.proto @@ -19,6 +19,7 @@ package maps.fleetengine.v1; import "google/api/field_behavior.proto"; import "google/api/resource.proto"; import "google/maps/fleetengine/v1/fleetengine.proto"; +import "google/maps/fleetengine/v1/traffic.proto"; import "google/protobuf/duration.proto"; import "google/protobuf/timestamp.proto"; import "google/protobuf/wrappers.proto"; @@ -37,8 +38,8 @@ message Trip { pattern: "providers/{provider}/trips/{trip}" }; - // In the format "providers/{provider}/trips/{trip}" - string name = 1; + // Output only. In the format "providers/{provider}/trips/{trip}" + string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY]; // ID of the vehicle making this trip. string vehicle_id = 2; @@ -63,9 +64,9 @@ message Trip { // information at the pickup point. StopLocation actual_pickup_arrival_point = 32 [(google.api.field_behavior) = INPUT_ONLY]; - // Either the estimated future time when the rider(s) will be picked up, or + // Output only. Either the estimated future time when the rider(s) will be picked up, or // the actual time when they were picked up. - google.protobuf.Timestamp pickup_time = 6; + google.protobuf.Timestamp pickup_time = 6 [(google.api.field_behavior) = OUTPUT_ONLY]; // Intermediate stops in order that the trip requests (in addition // to pickup and dropoff). Initially this will not be supported for shared @@ -107,9 +108,9 @@ message Trip { // information. StopLocation actual_dropoff_point = 23 [(google.api.field_behavior) = INPUT_ONLY]; - // Either the estimated future time when the rider(s) will be dropped off at + // Output only. Either the estimated future time when the rider(s) will be dropped off at // the final destination, or the actual time when they were dropped off. - google.protobuf.Timestamp dropoff_time = 8; + google.protobuf.Timestamp dropoff_time = 8 [(google.api.field_behavior) = OUTPUT_ONLY]; // Output only. The full path from the current location to the dropoff point, inclusive. // If this is a shared ride, this path could include waypoints from other @@ -124,20 +125,41 @@ message Trip { // UpdateTrip and CreateTrip calls, and NOT on GetTrip calls. repeated TripWaypoint vehicle_waypoints = 20; - // Anticipated route for this trip to the first entry in remaining_waypoints. - // If back_to_back or shared trips are enabled, the waypoint may belong to a + // Output only. Anticipated route for this trip to the first entry in remaining_waypoints. + // If back_to_back or shared trips are enabled, the waypoints may belong to a // different trip. - repeated google.type.LatLng route = 9; + repeated google.type.LatLng route = 9 [(google.api.field_behavior) = OUTPUT_ONLY]; - // The waypoint where current_route_segment ends. This can be supplied by + // Output only. An encoded path to the next waypoint. This field facilitates journey + // sharing between a Driver app and a Rider app. Your driver app is + // responsible for setting this field on all of its current trips by passing + // Vehicle.current_route_segment to UpdateVehicle. Note: This field is + // intended only for use by the Driver SDK and Consumer SDK. + string current_route_segment = 21 [(google.api.field_behavior) = OUTPUT_ONLY]; + + // Output only. Indicates the last time the route was modified. Note: This field is + // intended only for use by the Driver SDK and Consumer SDK. + google.protobuf.Timestamp current_route_segment_version = 17 [(google.api.field_behavior) = OUTPUT_ONLY]; + + // Output only. When available, the traffic conditions along the + // current_route_segment. Note: This field is intended only + // for use by the Driver SDK and Consumer SDK. + ConsumableTrafficPolyline current_route_segment_traffic = 28 [(google.api.field_behavior) = OUTPUT_ONLY]; + + // Output only. Indicates the last time the current_route_segment_traffic was modified. + // Note: This field is intended only for use by the Driver SDK and Consumer + // SDK. + google.protobuf.Timestamp current_route_segment_traffic_version = 30 [(google.api.field_behavior) = OUTPUT_ONLY]; + + // Output only. The waypoint where current_route_segment ends. This can be supplied by // drivers on UpdateVehicle calls either as a full trip waypoint, a waypoint - // latlng, or as a the last latlng of the current_route_segment. FleetEngine + // latlng, or as a the last latlng of the current_route_segment. Fleet Engine // will then do its best to interpolate to an actual waypoint if it is not // fully specified. It will be returned in GetTrip calls. It is not respected // in Create/Update Trip calls. - TripWaypoint current_route_segment_end_point = 24; + TripWaypoint current_route_segment_end_point = 24 [(google.api.field_behavior) = OUTPUT_ONLY]; - // The remaining driving distance in Trip.current_route_segment field. + // Output only. The remaining driving distance in Trip.current_route_segment field. // This field facilitates journey sharing between a driver and rider and // Fleet Engine does not update it. Your driver app is responsible for setting // field on all of its current trips by passing @@ -145,7 +167,7 @@ message Trip { // The value is unspecified if the trip is not assigned to a vehicle, or the // trip is inactive (completed or cancelled), or driver hasn't updated this // value. - google.protobuf.Int32Value remaining_distance_meters = 12; + google.protobuf.Int32Value remaining_distance_meters = 12 [(google.api.field_behavior) = OUTPUT_ONLY]; // Output only. The ETA to the next waypoint (the first entry in the // Trip.remaining_waypoints field). This field facilitates journey sharing @@ -162,29 +184,29 @@ message Trip { // Trip.eta_to_first_waypoint. google.protobuf.Duration remaining_time_to_first_waypoint = 27 [(google.api.field_behavior) = OUTPUT_ONLY]; - // Indicates the last time that `remaining_waypoints` was changed (a + // Output only. Indicates the last time that `remaining_waypoints` was changed (a // waypoint was added, removed, or changed). - google.protobuf.Timestamp remaining_waypoints_version = 19; + google.protobuf.Timestamp remaining_waypoints_version = 19 [(google.api.field_behavior) = OUTPUT_ONLY]; - // Indicates the last time the remaining_waypoints.path_to_waypoint and - // remaining_waypoints.traffic_to_waypoint were modified. Your client app - // should cache this value and pass it in GetTripRequest to ensure the - // paths and traffic for remaining_waypoints are only returned if updated. - google.protobuf.Timestamp remaining_waypoints_route_version = 29; + // Output only. Indicates the last time the `remaining_waypoints.path_to_waypoint` and + // `remaining_waypoints.traffic_to_waypoint` were modified. Your client app + // should cache this value and pass it in `GetTripRequest` to ensure the + // paths and traffic for `remaining_waypoints` are only returned if updated. + google.protobuf.Timestamp remaining_waypoints_route_version = 29 [(google.api.field_behavior) = OUTPUT_ONLY]; - // Indicates the number of passengers on this trip and does not include the - // driver. A vehicle must have available_capacity to be returned - // in SearchTrips. - int32 number_of_passengers = 10; + // Immutable. Indicates the number of passengers on this trip and does not include the + // driver. A vehicle must have available capacity to be returned + // in SearchVehicles. + int32 number_of_passengers = 10 [(google.api.field_behavior) = IMMUTABLE]; - // Indicates the last reported location of the vehicle along the route. - VehicleLocation last_location = 11; + // Output only. Indicates the last reported location of the vehicle along the route. + VehicleLocation last_location = 11 [(google.api.field_behavior) = OUTPUT_ONLY]; - // Indicates whether the vehicle's last_location can be snapped to + // Output only. Indicates whether the vehicle's last_location can be snapped to // the current_route_segment. False if last_location or current_route_segment // doesn't exist. // It is computed by Fleet Engine. Any update from clients will be ignored. - bool last_location_snappable = 26; + bool last_location_snappable = 26 [(google.api.field_behavior) = OUTPUT_ONLY]; // The subset of Trip fields that are populated and how they should be // interpreted. @@ -196,11 +218,14 @@ message StopLocation { // Required. Denotes the actual location. google.type.LatLng point = 1 [(google.api.field_behavior) = REQUIRED]; - // The timestamp when the location was measured. + // Indicates when the stop happened. google.protobuf.Timestamp timestamp = 2; - // Indicates when the stop actually happened. - google.protobuf.Timestamp stop_time = 3; + // Input only. Deprecated. Use the timestamp field. + google.protobuf.Timestamp stop_time = 3 [ + deprecated = true, + (google.api.field_behavior) = INPUT_ONLY + ]; } // The status of a trip indicating its progression. diff --git a/google/maps/fleetengine/v1/vehicle_api.proto b/google/maps/fleetengine/v1/vehicle_api.proto index 88a7c6623c..dd7f07d4ec 100644 --- a/google/maps/fleetengine/v1/vehicle_api.proto +++ b/google/maps/fleetengine/v1/vehicle_api.proto @@ -39,28 +39,32 @@ option objc_class_prefix = "CFE"; service VehicleService { option (google.api.default_host) = "fleetengine.googleapis.com"; - // CreateVehicle instantiates a new vehicle associated with a rideshare - // provider in the Fleet Engine. Vehicles must have a unique vehicle ID. + // 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: + // The following `Vehicle` fields are required when creating a `Vehicle`: // - // * vehicleState - // * supportedTripTypes - // * maximumCapacity - // * vehicleType + // * `vehicleState` + // * `supportedTripTypes` + // * `maximumCapacity` + // * `vehicleType` // - // The following Vehicle fields are ignored when creating a Vehicle: + // The following `Vehicle` fields are ignored when creating a `Vehicle`: // - // * name - // * currentTrips - // * availableCapacity - // * current_route_segment - // * current_route_segment_version - // * waypoint - // * waypoints_version - // * remaining_distance_meters - // * eta_to_next_waypoint - // * navigation_status + // * `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) { @@ -70,26 +74,29 @@ service VehicleService { }; } - // GetVehicle returns a vehicle from the Fleet Engine. + // Returns a vehicle from the Fleet Engine. rpc GetVehicle(GetVehicleRequest) returns (Vehicle) { option (google.api.http) = { get: "/v1/{name=providers/*/vehicles/*}" }; } - // UpdateVehicle writes updated vehicle data to the Fleet Engine. + // Writes updated vehicle data to the Fleet Engine. // - // When updating a Vehicle, the following fields cannot be updated since they - // are managed by 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 + // * `currentTrips` + // * `availableCapacity` + // * `current_route_segment_version` + // * `waypoints_version` // - // The vehicle name also cannot be updated. + // The vehicle `name` also cannot be updated. // - // The waypoints field can be updated, but must contain all the waypoints + // 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) = { @@ -98,8 +105,8 @@ service VehicleService { }; } + // Deprecated: Use the `UpdateVehicle` method instead. // UpdateVehicleLocation updates the location of the vehicle. - // This method is deprecated. Use UpdateVehicle method instead. rpc UpdateVehicleLocation(UpdateVehicleLocationRequest) returns (VehicleLocation) { option deprecated = true; option (google.api.http) = { @@ -108,11 +115,11 @@ service VehicleService { }; } - // UpdateVehicleAttributes partially updates a vehicle's attributes. + // 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, + // 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. + // `UpdateVehicleRequest`, attributes not in the request would be removed. rpc UpdateVehicleAttributes(UpdateVehicleAttributesRequest) returns (UpdateVehicleAttributesResponse) { option (google.api.http) = { post: "/v1/{name=providers/*/vehicles/*}:updateAttributes" @@ -120,7 +127,7 @@ service VehicleService { }; } - // ListVehicles returns a paginated list of vehicles associated with + // Returns a paginated list of vehicles associated with // a provider that match the request options. rpc ListVehicles(ListVehiclesRequest) returns (ListVehiclesResponse) { option (google.api.http) = { @@ -128,7 +135,7 @@ service VehicleService { }; } - // SearchVehicles returns a list of vehicles that match the request options. + // 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" @@ -136,12 +143,11 @@ service VehicleService { }; } - // SearchFuzzedVehicles returns a list of vehicles that match the request - // options with their locations fuzzed. - // Request does not support 'order_by' field. - // Vehicle matches in response will be in order of distance from pickup point. - // Vehicle matches in response will only have 'vehicle' and 'trip_type' field - // set. + // 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" @@ -150,55 +156,65 @@ service VehicleService { } } -// CreateVehicle request message. +// `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) + // 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; must be unique per provider. The actual - // format and value is opaque to the Fleet Engine and is determined - // by the provider. + // Required. Unique Vehicle ID; must be unique per provider. + // Subject to the following normalization and restrictions: + // + // 1. IDs must be valid Unicode strings. + // 2. IDs are limited to a maximum length of 64 characters. + // 3. IDs will be normalized according to Unicode Normalization Form C + // (http://www.unicode.org/reports/tr15/). + // 4. IDs 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: // - // * vehicle_state - // * supported_trip_types - // * maximum_capacity - // * vehicle_type + // * `vehicleState` + // * `supportedTripTypes` + // * `maximumCapacity` + // * `vehicleType` // // When creating a Vehicle, the following fields are ignored: // - // * name - // * current_trips - // * available_capacity - // * current_route_segment - // * current_route_segment_version - // * waypoints - // * waypoints_version - // * remaining_distance_meters - // * eta_to_next_waypoint - // * navigation_status + // * `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 will be used if provided. + // All other fields are optional and used if provided. Vehicle vehicle = 5 [(google.api.field_behavior) = REQUIRED]; } -// GetVehicle request message. +// `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) + // `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 [ @@ -209,51 +225,55 @@ message GetVehicleRequest { ]; // Indicates the minimum timestamp (exclusive) for which - // vehicle.current_route_segment is retrieved. - // If route is unchanged since this timestamp, the current_route_segment + // `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. + // `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 data is unchanged since this timestamp, the - // vehicle.waypoints data is not set in the response. If this field is - // unspecified, vehicle.waypoints is always retrieved. + // 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. +// `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) + // `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. - // - // Note that if the name is also specified in the name field of the - // vehicle and name is set in the update_mask, both names must be the - // same. Otherwise it is an Error. string name = 3 [(google.api.field_behavior) = REQUIRED]; - // Required. The Vehicle entity update to apply. When updating a Vehicle, + // Required. The `Vehicle` entity values to apply. When updating a `Vehicle`, // the following fields may not be updated as they are managed by the - // Fleet Engine. - // current_trips - // available_capacity - // current_route_segment_version - // waypoints_version - // Furthermore, the name of the vehicle cannot be updated. + // 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. - // The update_mask must contain at least one field. + // 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. +// `UpdateVehicleLocation` request message. message UpdateVehicleLocationRequest { option deprecated = true; @@ -261,50 +281,47 @@ message UpdateVehicleLocationRequest { 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) + // `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 location to update to. The last_location and update_time + // 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 current vehicle state to either ONLINE or OFFLINE; - // if set to UNKNOWN_VEHICLE_STATE, vehicle state will not be altered. + // 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. +// `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) + // 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 attributes to update; - // unmentioned attributes will not be altered or removed. - // At most 20 attributes; the combined "key:value" string length cannot - // exceed 256. + // 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. +// `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. +// `SearchVehicles` request message. message SearchVehiclesRequest { - // Specifies the sort order of the vehicle matches in the response. + // 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; @@ -312,27 +329,26 @@ message SearchVehiclesRequest { // Ascending order by vehicle driving time to the pickup point. PICKUP_POINT_ETA = 1; - // Ascending order by the vehicle driving distance to the pickup point. + // 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. + // can only be used if the dropoff point is specified in the request. DROPOFF_POINT_ETA = 3; - // Ascending order by straightline distance from vehicle location to pickup - // location. This is used primarily as a backup if the maps backend is not - // reachable. + // 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 match cost. + // Ascending order by the configured match cost. COST = 5; } // 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) + // 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]; @@ -341,50 +357,54 @@ message SearchVehiclesRequest { 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. + // `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. + // 400 and 10000 meters (inclusive). int32 pickup_radius_meters = 6 [(google.api.field_behavior) = REQUIRED]; - // Required. Specifies the maximum number of available vehicles to return. By - // default, the Fleet Engine limits the number to 50. + // 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 minimum number of passengers allowed in the - // vehicle. Must number must be greater than or equal to one. The driver is - // not considered in the capacity search. This number indicates the number of - // passengers being considered for a trip. + // 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. Restricts the search to only those vehicles that support at least // one of the specified trip types. + // + // At the present time, only `EXCLUSIVE` is supported. 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 back from now. If this field is not + // 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 those vehicles with the specified types. + // 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 the - // requiredAttributes and requiredOneOfAttributes fields. + // Callers can form complex logical operations using any combination of the + // `required_attributes`, `required_one_of_attributes`, and + // `required_one_of_attribute_sets` 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: + // `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_attribute[0] AND required_attribute[1] AND ...) + // (required_attributes[0] AND required_attributes[1] AND ...) // AND - // (required_one_of_attribute[0][0] OR required_one_of_attribute[0][1] OR ...) + // (required_one_of_attributes[0][0] OR required_one_of_attributes[0][1] OR + // ...) // AND - // (required_one_of_attribute[1][0] OR required_one_of_attribute[1][1] OR ...) + // (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. @@ -394,60 +414,76 @@ message SearchVehiclesRequest { repeated VehicleAttribute required_attributes = 12; // Restricts the search to only those vehicles with at least one of - // the specified attributes applied to each VehicleAttributeList. Within each + // 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. + // inclusive disjunction/OR operation in each `VehicleAttributeList` and a + // conjunction/AND operation across the collection of `VehicleAttributeList`. repeated VehicleAttributeList required_one_of_attributes = 15; - // Restricts the search to only those vehicles with at least one set of the - // specified attributes in the VehicleAttributeList. Within each list, a + // `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 + // ...) + // ``` + // + // 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. + // operation in each `VehicleAttributeList` and inclusive disjunction/OR + // operation across the collection of `VehicleAttributeList`. repeated VehicleAttributeList required_one_of_attribute_sets = 20; - // Required. Specifies ordering criterion for results. + // Required. Specifies the desired ordering criterion for results. VehicleMatchOrder order_by = 13 [(google.api.field_behavior) = REQUIRED]; - // Indicates if a vehicle with an active trip is eligible for - // another match. If `false`, a vehicle is excluded from search results. - // If `true`, search results include vehicles with `TripStatus` of - // `ENROUTE_TO_DROPOFF`. The services only use this field if - // the `SearchVehicles` request has `TripType` set to EXCLUSIVE. - // Default value is `false`. + // 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 ID of the trip the searchVehicleRequest is - // associated with. + // Indicates the trip associated with this `SearchVehicleRequest`. + // Unique Trip ID; must be unique per provider. + // Subject to the following normalization and restrictions: + // + // 1. IDs must be valid Unicode strings. + // 2. IDs are limited to a maximum length of 64 characters. + // 3. IDs will be normalized according to Unicode Normalization Form C + // (http://www.unicode.org/reports/tr15/). + // 4. IDs may not contain any of the following ASCII characters: '/', ':', + // '\\', '?', or '#'. string trip_id = 19; } -// SearchVehicles response message. +// `SearchVehicles` response message. message SearchVehiclesResponse { - // List of vehicles that match the request options. - // - // Ordered by ascending vehicle_pickup_eta, with ties broken by ascending - // trip_type enum value, followed by matches that don't have - // vehicle_pickup_eta set. - // - // Example response: (Logically represented, not actual response fields): - // - // * (VehicleId: Vehicle1, ETA: 10 AM, TripType: SHARED), - // * (VehicleId: Vehicle2, ETA: 10 AM, TripType: EXCLUSIVE), - // * (VehicleId: Vehicle3, ETA: 11 AM, TripType: EXCLUSIVE), - // * (VehicleId: Vehicle4, ETA: Not set, TripType: SHARED), - // * (VehicleId: Vehicle5, ETA: Not set, TripType: EXCLUSIVE) + // List of vehicles that match the `SearchVehiclesRequest` criteria, ordered + // according to `SearchVehiclesRequest.order_by` field. repeated VehicleMatch matches = 1; } -// ListVehicles request message. +// `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) + // 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]; @@ -456,88 +492,110 @@ message ListVehiclesRequest { // Default value: 100. int32 page_size = 3; - // The next_page_token value returned from a previous response, if any. + // 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. - // The driver is not considered in the capacity search. - // This is just the number of passengers being considered for a trip. - // If set, must be greater or equal to 0. + // 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 search to only those vehicles that support at least + // Restrict the response to vehicles that support at least // one of the specified trip types. repeated TripType trip_types = 7; - // Restrict the search to only those vehicles that have updated + // 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 search to those vehicles with the specified type categories. + // 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 the - // requiredAttributes and requiredOneOfAttributes fields. + // Callers can form complex logical operations using any combination of the + // `required_attributes`, `required_one_of_attributes`, and + // `required_one_of_attribute_sets` 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: + // `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_attribute[0] AND required_attribute[1] AND ...) + // (required_attributes[0] AND required_attributes[1] AND ...) // AND - // (required_one_of_attribute[0][0] OR required_one_of_attribute[0][1] OR ...) + // (required_one_of_attributes[0][0] OR required_one_of_attributes[0][1] OR + // ...) // AND - // (required_one_of_attribute[1][0] OR required_one_of_attribute[1][1] OR ...) + // (required_one_of_attributes[1][0] OR required_one_of_attributes[1][1] OR + // ...) // ``` // - // Restrict the search to only those vehicles - // with the specified attributes. This field is a conjunction/AND operation. - // Your app can specify up to 100 attributes; however, the combined - // key:value string length cannot exceed 1024 characters. + // Restrict the response to vehicles with the specified attributes. This field + // is a conjunction/AND operation. Your app can specify up to 100 attributes; + // however, the combined key:value string length cannot exceed 1024 + // characters. repeated string required_attributes = 10; - // Restrict the search to only those vehicles with at least one - // of the specified attributes applied to each VehicleAttributeList. + // 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. - // Format: key1:value1|key2:value2|key3:value3... + // `VehicleAttributeList` and a conjunction/AND operation across the + // collection of `VehicleAttributeList`. Format: + // key1:value1|key2:value2|key3:value3... repeated string required_one_of_attributes = 13; - // Restrict the search to only those vehicles with at least one set of the - // specified attributes in the 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. - // Format: key1:value1|key2:value2|key3:value3... + // `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`. Format: + // key1:value1|key2:value2|key3:value3... repeated string required_one_of_attribute_sets = 15; - // Restrict the search to only those vehicles that have this vehicle state. + // 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. +// `ListVehicles` response message. message ListVehiclesResponse { - // Depends on vehicles matching request criteria. - // There will be a maximum number of vehicles returned based on the page_size + // 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 in the list. + // more vehicles that meet the request criteria. string next_page_token = 2; - // Required. Total number of vehicles matching request criteria across all pages. + // Required. Total number of vehicles matching the request criteria across all pages. int64 total_size = 3 [(google.api.field_behavior) = REQUIRED]; } -// Waypoint describes intermediate points along a route. +// Describes intermediate points along a route. message Waypoint { // The location of this waypoint. google.type.LatLng lat_lng = 1; @@ -546,24 +604,29 @@ message Waypoint { google.protobuf.Timestamp eta = 2; } -// VehicleMatch contains the vehicle, ETA, and distance calculations for a -// vehicle that matches the SearchVehiclesRequest. +// 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; - // Exclusive vehicle trip match + // The vehicle currently has no trip assigned to it and can proceed to the + // pickup point. EXCLUSIVE = 1; - // Back to back ride match. + // 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; - // Carpool ride match. + // The vehicle has sufficient capacity for a shared ride. CARPOOL = 3; - // Carpool ride match. The car has an active exclusive trip. + // 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; } @@ -572,27 +635,29 @@ message VehicleMatch { // 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. + // 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 vehicle's driving distance to the pickup point specified in - // the request, including any intermediate pickup or dropoff points for - // an existing ride. An empty value indicates a failure in calculating - // distance for the vehicle. + // 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, including intermediate waypoints for - // existing trips. + // 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 any required visits for active - // trips that must be completed before the vehicle visits the dropoff_point - // specified in the request. The value will only be populated when a - // dropoff_point is specified in the request. An empty value indicates - // a failure in calculating the ETA for the vehicle to reach - // the dropoff_point. + // 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 @@ -600,9 +665,9 @@ message VehicleMatch { // 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 + // `dropoff_point` is specified in the request. An empty value indicates // a failure in calculating the distance from the pickup to - // dropoff points specified in the request. + // 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 @@ -610,8 +675,8 @@ message VehicleMatch { TripType trip_type = 6 [(google.api.field_behavior) = REQUIRED]; // The ordered list of waypoints used to calculate the ETA. The list - // will include the vehicle location, the pickup/drop off points of active - // trips for the vehicle and the pickup/dropoff points provided in the + // 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; @@ -619,17 +684,17 @@ message VehicleMatch { // Type of the vehicle match. VehicleMatchType vehicle_match_type = 8; - // The method the caller requested for sorting vehicle matches. + // The order requested for sorting vehicle matches. SearchVehiclesRequest.VehicleMatchOrder requested_ordered_by = 9; - // The actual method that is used to order this vehicle. In normal cases this - // will match the 'order_by' field from the request, however in certain - // circumstances such as a failure of google maps backends, a different method - // may be used (such as PICKUP_POINT_STRAIGHT_DISTANCE). + // 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; } -// This messages allows a list-of-list datatype for VehicleAttribute. +// A list-of-lists datatype for vehicle attributes. message VehicleAttributeList { // A list of attributes in this collection. repeated VehicleAttribute attributes = 1; diff --git a/google/maps/fleetengine/v1/vehicles.proto b/google/maps/fleetengine/v1/vehicles.proto index b9787652de..8b66a50fa3 100644 --- a/google/maps/fleetengine/v1/vehicles.proto +++ b/google/maps/fleetengine/v1/vehicles.proto @@ -35,17 +35,17 @@ message Vehicle { pattern: "providers/{provider}/vehicles/{vehicle}" }; - // Types of vehicles that may be filtered for in SearchVehicles. + // The type of vehicle. message VehicleType { // Vehicle type categories enum Category { - // Default, used for unspecified or unrecognized vehicle types. + // Default, used for unspecified or unrecognized vehicle categories. UNKNOWN = 0; // An automobile. AUTO = 1; - // Any vehicle that acts as a taxi. + // Any vehicle that acts as a taxi (typically licensed or regulated). TAXI = 2; // Generally, a vehicle with a large storage capacity. @@ -59,9 +59,9 @@ message Vehicle { Category category = 1; } - // The unique name for this vehicle. - // The format is providers/{provider}/vehicles/{vehicle} - string name = 1; + // Output only. The unique name for this vehicle. + // The format is `providers/{provider}/vehicles/{vehicle}`. + string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY]; // The vehicle state. VehicleState vehicle_state = 2; @@ -69,106 +69,101 @@ message Vehicle { // Supported trip types. repeated TripType supported_trip_types = 3; - // List of IDs for trips in progress. - repeated string current_trips = 4; + // Output only. List of `trip_id`'s for trips currently assigned to this vehicle. + repeated string current_trips = 4 [(google.api.field_behavior) = OUTPUT_ONLY]; // Last reported location of the vehicle. VehicleLocation last_location = 5; - // Maximum capacity of the vehicle. This is the total numbers of riders - // on trips this vehicle can contain. The driver is not considered in - // this value. This value must be greater than or equal to one. + // The total numbers of riders this vehicle can carry. The driver is not + // considered in this value. This value must be greater than or equal to one. int32 maximum_capacity = 6; - // The current available capacity of the vehicle. This is the - // maximum_capacity minus the current number of riders. - int32 available_capacity = 7; - - // List of vehicle service attributes. + // List of vehicle attributes. A vehicle can have at most 50 + // attributes. repeated VehicleAttribute attributes = 8; - // The type of this Vehicle. Can be filtered during SearchVehicles. Also - // influences ETA and route calculations. + // The type of this vehicle. Can be used to filter vehicles in + // `SearchVehicles` results. Also influences ETA and route calculations. VehicleType vehicle_type = 9; // License plate information for the vehicle. LicensePlate license_plate = 10; - // Deprecated. Use vehicle.waypoint instead. + // Deprecated: Use `Vehicle.waypoints` instead. repeated TerminalLocation route = 12 [deprecated = true]; // The polyline specifying the route the driver app intends to take to // the next waypoint. Your driver app updates this every time a waypoint is // passed or the driver reroutes. This list is also returned in - // Trip.current_route_segment for all active trips assigned to the vehicle. + // `Trip.current_route_segment` for all active trips assigned to the vehicle. // Note: This field is intended only for use by the Driver SDK. string current_route_segment = 20; - // Time when current_route_segment was set. This field is ignored in - // UpdateVehicleRequests as it is calculated by the server. It should be - // stored by client and passed in to future requests to prevent returning - // routes to first way point that haven't changed. - google.protobuf.Timestamp current_route_segment_version = 15; + // Input only. Fleet Engine uses this information to improve its + // understanding of a Trip, but does not populate the field in its responses. + // Note: This field is intended only for use by the Driver SDK. + TrafficPolylineData current_route_segment_traffic = 28 [(google.api.field_behavior) = INPUT_ONLY]; - // The waypoint where current_route_segment ends. This can be supplied by - // drivers on UpdateVehicle calls either as a full trip waypoint, a waypoint - // latlnt, or as a the last latlng of the current_route_segment. FleetEngine - // will then do its best to interpolate to an actual waypoint if it is not - // fully specified. This field is ignored in UpdateVehicle calls unless - // current_route_segment is also specified. + // Output only. Time when `current_route_segment` was set. It should be + // stored by the client and passed in future `GetVehicle` requests to + // prevent returning routes that haven't changed. + google.protobuf.Timestamp current_route_segment_version = 15 [(google.api.field_behavior) = OUTPUT_ONLY]; + + // The waypoint where `current_route_segment` ends. This can be supplied by + // drivers on `UpdateVehicle` calls either as a full trip waypoint, a waypoint + // `LatLng`, or as the last `LatLng` of the `current_route_segment`. Fleet + // Engine will then do its best to interpolate to an actual waypoint if it is + // not fully specified. This field is ignored in `UpdateVehicle` calls unless + // `current_route_segment` is also specified. TripWaypoint current_route_segment_end_point = 24; - // The remaining driving distance for the 'current_route_segment'. This field + // The remaining driving distance for the `current_route_segment`. This field // facilitates journey sharing between the Driver app and the Consumer app. - // This value is updated by the Driver SDK. Fleet Engine does not update it. - // This field is also returned in Trip.remaining_distance_meters for all - // active trips assigned to the vehicle. The value is unspecified if the - // `Vehicle.current_route_segment` field is empty, or if the Driver app has - // not updated its value. + // This value is provided by the Driver SDK. This field is also returned in + // `Trip.remaining_distance_meters` for all active trips assigned to the + // vehicle. The value is unspecified if the `current_route_segment` field is + // empty, or if the Driver app has not updated its value. google.protobuf.Int32Value remaining_distance_meters = 18; - // The ETA to the next waypoint that is the first entry in Vehicle.waypoint + // The ETA to the first entry in the `waypoints` // field. This field facilitates journey sharing between a Driver app and a - // Consumer app and is updated by the Driver SDK, and Fleet Engine does not - // update it. This field is also returned in Trip.eta_to_first_waypoint for - // all active trips assigned to the vehicle. The value is unspecified if the - // Vehicle.waypoint field is empty, or the Driver app has not updated its - // value. + // Consumer app. Is is provided by the Driver SDK. This field is also returned + // in `Trip.eta_to_first_waypoint` for all active trips assigned to the + // vehicle. The value is unspecified if the `waypoints` field is empty, or the + // Driver app has not updated its value. google.protobuf.Timestamp eta_to_first_waypoint = 19; - // The remaining driving time for the 'current_route_segment'. This field + // Input only. The remaining driving time for the `current_route_segment`. This field // facilitates journey sharing between the Driver app and the Consumer app. // This value is updated by the Driver SDK. Fleet Engine does not update it. // The value is unspecified if the `Vehicle.current_route_segment` field is // empty, or if the Driver app has not updated its value. This value should - // match eta_to_first_waypoint - current_time if all parties are using the - // same clock. This field is currently write-only and will not yet be - // populated in Vehicle's get/update/search operations. When updating a - // vehicle, if you update both eta_to_first_waypoint and - // remaining_time_seconds in the same request, then only - // remaining_time_seconds is considered. - google.protobuf.Int32Value remaining_time_seconds = 25; + // match `eta_to_first_waypoint` - `current_time` if all parties are using the + // same clock. When updating a + // vehicle, if you update both `eta_to_first_waypoint` and + // `remaining_time_seconds` in the same request, `remaining_time_seconds` + // takes precedence. + google.protobuf.Int32Value remaining_time_seconds = 25 [(google.api.field_behavior) = INPUT_ONLY]; - // The remaining set of waypoints assigned to this Vehicle. + // The remaining waypoints assigned to this Vehicle. repeated TripWaypoint waypoints = 22; - // Last time the waypoints was updated. Client should cache - // this value and pass it in GetVehicleRequest to ensure the - // waypoints.path_to_waypoint is only returned if it is updated - google.protobuf.Timestamp waypoints_version = 16; + // Output only. Last time the `waypoints` field was updated. Clients should cache + // this value and pass it in `GetVehicleRequest` to ensure the + // `waypoints` field is only returned if it is updated. + google.protobuf.Timestamp waypoints_version = 16 [(google.api.field_behavior) = OUTPUT_ONLY]; - // Indicates if the driver accepts back-to-back rides. If - // `true`, services include the vehicle for back-to-back matches. - // If `false`, services exclude the vehicle from back-to-back matches. - // Default value is `false`. + // Indicates if the driver accepts back-to-back trips. If `true`, + // `SearchVehicles` may include the vehicle even if it is currently assigned + // to a trip. The default value is `false`. bool back_to_back_enabled = 23; - // Vehicle's navigation status. + // The vehicle's navigation status. NavigationStatus navigation_status = 26; - // Information about various device settings. This is internal debug only - // field, not included in the response. - DeviceSettings device_settings = 27; + // Input only. Information about settings in the mobile device being used by the driver. + DeviceSettings device_settings = 27 [(google.api.field_behavior) = INPUT_ONLY]; } // Information about the device's battery. @@ -183,7 +178,7 @@ message BatteryInfo { float battery_percentage = 3; } -// Information about various settings on the device. +// Information about various settings on the mobile device. message DeviceSettings { // How location features are set to behave on the device when battery saver is // on. @@ -199,17 +194,16 @@ message DeviceSettings { BatteryInfo battery_info = 4; } -// The license plate information of the Vehicle. This is used to support -// congestion pricing restrictions in certain areas. To avoid storing +// The license plate information of the Vehicle. To avoid storing // personally-identifiable information, only the minimum information // about the license plate is stored as part of the entity. message LicensePlate { - // Required. CLDR Country/Region Code. For example, "US" for United States, - // or "IN" for India. + // Required. CLDR Country/Region Code. For example, `US` for United States, + // or `IN` for India. string country_code = 1 [(google.api.field_behavior) = REQUIRED]; // The last digit of the license plate or "-1" to denote no numeric value - // present in the license plate. + // is present in the license plate. // // * "ABC 1234" -> "4" // * "AB 123 CD" -> "3" @@ -217,20 +211,63 @@ message LicensePlate { string last_character = 2; } -// The state of a Vehicle. +// Describes how clients should color one portion of the polyline along the +// route. +message VisualTrafficReportPolylineRendering { + // One road stretch that should be rendered. + message RoadStretch { + // The traffic style, indicating traffic speed. + enum Style { + // No style selected. + STYLE_UNSPECIFIED = 0; + + // Traffic is slowing down. + SLOWER_TRAFFIC = 1; + + // There is a traffic jam. + TRAFFIC_JAM = 2; + } + + // Required. The style to apply. + Style style = 1 [(google.api.field_behavior) = REQUIRED]; + + // Required. The style should be applied between `[offset_meters, offset_meters + + // length_meters)`. + int32 offset_meters = 2 [(google.api.field_behavior) = REQUIRED]; + + // Required. The length of the path where to apply the style. + int32 length_meters = 3 [(google.api.field_behavior) = REQUIRED]; + } + + // Optional. Road stretches that should be rendered along the polyline. Note that + // the stretches are guaranteed to not overlap, and that they do not + // necessarily span the full route. In the absence of a road stretch to style, + // the client should apply the default for the route. + repeated RoadStretch road_stretch = 1 [(google.api.field_behavior) = OPTIONAL]; +} + +// Traffic conditions along the expected vehicle route. +message TrafficPolylineData { + // A polyline rendering of how fast traffic is for all regions along + // one stretch of a customer ride. + VisualTrafficReportPolylineRendering traffic_rendering = 1; +} + +// The state of a `Vehicle`. enum VehicleState { // Default, used for unspecified or unrecognized vehicle states. UNKNOWN_VEHICLE_STATE = 0; - // The vehicle is not accepting new trips. + // The vehicle is not accepting new trips. Note: the vehicle may continue to + // operate in this state while completing a trip assigned to it. OFFLINE = 1; // The vehicle is accepting new trips. ONLINE = 2; } -// How location features are set to behave on the device when battery saver is -// on. +// How location features are configured to behave on the mobile device when the +// devices "battery saver" feature is on. // (https://developer.android.com/reference/android/os/PowerManager#getLocationPowerSaveMode()) enum LocationPowerSaveMode { // Undefined LocationPowerSaveMode