path: root/third_party/googleapis/google/maps/routing/v2/routes_service.proto

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

syntax = "proto3";

package google.maps.routing.v2;

import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/maps/routing/v2/fallback_info.proto";
import "google/maps/routing/v2/polyline.proto";
import "google/maps/routing/v2/route.proto";
import "google/maps/routing/v2/route_modifiers.proto";
import "google/maps/routing/v2/route_travel_mode.proto";
import "google/maps/routing/v2/routing_preference.proto";
import "google/maps/routing/v2/units.proto";
import "google/maps/routing/v2/waypoint.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/timestamp.proto";
import "google/rpc/status.proto";

option cc_enable_arenas = true;
option csharp_namespace = "Google.Maps.Routing.V2";
option go_package = "google.golang.org/genproto/googleapis/maps/routing/v2;routing";
option java_multiple_files = true;
option java_outer_classname = "RoutesServiceProto";
option java_package = "com.google.maps.routing.v2";
option objc_class_prefix = "GMRV2";
option php_namespace = "Google\\Maps\\Routing\\V2";
option ruby_package = "Google::Maps::Routing::V2";

// The Routes API.
service Routes {
  option (google.api.default_host) = "routes.googleapis.com";

  // Returns the primary route along with optional alternate routes, given a set
  // of terminal and intermediate waypoints.
  //
  // **NOTE:** This method requires that you specify a response field mask in
  // the input. You can provide the response field mask by using URL parameter
  // `$fields` or `fields`, or by using an HTTP/gRPC header `X-Goog-FieldMask`
  // (see the [available URL parameters and
  // headers](https://cloud.google.com/apis/docs/system-parameters). The value
  // is a comma separated list of field paths. See detailed documentation about
  // [how to construct the field
  // paths](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/field_mask.proto).
  //
  // For example, in this method:
  //
  // * Field mask of all available fields (for manual inspection):
  //   `X-Goog-FieldMask: *`
  // * Field mask of Route-level duration, distance, and polyline (an example
  // production setup):
  //   `X-Goog-FieldMask:
  //   routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline`
  //
  // Google discourage the use of the wildcard (`*`) response field mask, or
  // specifying the field mask at the top level (`routes`), because:
  //
  // * Selecting only the fields that you need helps our server save computation
  // cycles, allowing us to return the result to you with a lower latency.
  // * Selecting only the fields that you need
  // in your production job ensures stable latency performance. We might add
  // more response fields in the future, and those new fields might require
  // extra computation time. If you select all fields, or if you select all
  // fields at the top level, then you might experience performance degradation
  // because any new field we add will be automatically included in the
  // response.
  // * Selecting only the fields that you need results in a smaller response
  // size, and thus higher network throughput.
  rpc ComputeRoutes(ComputeRoutesRequest) returns (ComputeRoutesResponse) {
    option (google.api.http) = {
      post: "/directions/v2:computeRoutes"
      body: "*"
    };
  }

  // Takes in a list of origins and destinations and returns a stream containing
  // route information for each combination of origin and destination.
  //
  // **NOTE:** This method requires that you specify a response field mask in
  // the input. You can provide the response field mask by using the URL
  // parameter `$fields` or `fields`, or by using the HTTP/gRPC header
  // `X-Goog-FieldMask` (see the [available URL parameters and
  // headers](https://cloud.google.com/apis/docs/system-parameters). The value
  // is a comma separated list of field paths. See this detailed documentation
  // about [how to construct the field
  // paths](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/field_mask.proto).
  //
  // For example, in this method:
  //
  // * Field mask of all available fields (for manual inspection):
  //   `X-Goog-FieldMask: *`
  // * Field mask of route durations, distances, element status, condition, and
  //   element indices (an example production setup):
  //   `X-Goog-FieldMask:
  //   originIndex,destinationIndex,status,condition,distanceMeters,duration`
  //
  // It is critical that you include `status` in your field mask as otherwise
  // all messages will appear to be OK. Google discourages the use of the
  // wildcard (`*`) response field mask, because:
  //
  // * Selecting only the fields that you need helps our server save computation
  // cycles, allowing us to return the result to you with a lower latency.
  // * Selecting only the fields that you need in your production job ensures
  // stable latency performance. We might add more response fields in the
  // future, and those new fields might require extra computation time. If you
  // select all fields, or if you select all fields at the top level, then you
  // might experience performance degradation because any new field we add will
  // be automatically included in the response.
  // * Selecting only the fields that you need results in a smaller response
  // size, and thus higher network throughput.
  rpc ComputeRouteMatrix(ComputeRouteMatrixRequest) returns (stream RouteMatrixElement) {
    option (google.api.http) = {
      post: "/distanceMatrix/v2:computeRouteMatrix"
      body: "*"
    };
  }
}

// ComputeRoutes request message.
message ComputeRoutesRequest {
  // Required. Origin waypoint.
  Waypoint origin = 1 [(google.api.field_behavior) = REQUIRED];

  // Required. Destination waypoint.
  Waypoint destination = 2 [(google.api.field_behavior) = REQUIRED];

  // Optional. A set of waypoints along the route (excluding terminal points),
  // for either stopping at or passing by. Up to 25 intermediate waypoints are
  // supported.
  repeated Waypoint intermediates = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Specifies the mode of transportation.
  RouteTravelMode travel_mode = 4 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Specifies how to compute the route. The server
  // attempts to use the selected routing preference to compute the route. If
  //  the routing preference results in an error or an extra long latency, then
  // an error is returned. In the future, we might implement a fallback
  // mechanism to use a different option when the preferred option does not give
  // a valid result. You can specify this option only when the `travel_mode` is
  // `DRIVE` or `TWO_WHEELER`, otherwise the request fails.
  RoutingPreference routing_preference = 5 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Specifies your preference for the quality of the polyline.
  PolylineQuality polyline_quality = 6 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Specifies the preferred encoding for the polyline.
  PolylineEncoding polyline_encoding = 12 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The departure time. If you don't set this value, then this value
  // defaults to the time that you made the request. If you set this value to a
  // time that has already occurred, then the request fails.
  google.protobuf.Timestamp departure_time = 7 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Specifies whether to calculate alternate routes in addition to the route.
  bool compute_alternative_routes = 8 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A set of conditions to satisfy that affect the way routes are
  // calculated.
  RouteModifiers route_modifiers = 9 [(google.api.field_behavior) = OPTIONAL];

  // Optional. 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. See
  // [Language Support](https://developers.google.com/maps/faq#languagesupport)
  // for the list of supported languages. When you don't provide this value, the
  // display language is inferred from the location of the route request.
  string language_code = 10 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Specifies the units of measure for the display fields. This
  // includes the `instruction` field in `NavigationInstruction`. The units of
  // measure used for the route, leg, step distance, and duration are not
  // affected by this value. If you don't provide this value, then the display
  // units are inferred from the location of the request.
  Units units = 11 [(google.api.field_behavior) = OPTIONAL];
}

// ComputeRoutes the response message.
message ComputeRoutesResponse {
  // Contains an array of computed routes (up to three) when you specify
  // compute_alternatives_routes, and contains just one route when you don't.
  // When this array contains multiple entries, the first one is the most
  // recommended route. If the array is empty, then it means no route could be
  // found.
  repeated Route routes = 1;

  // In some cases when the server is not able to compute the route results with
  // all of the input preferences, it may fallback to using a different way of
  // computation. When fallback mode is used, this field contains detailed info
  // about the fallback response. Otherwise this field is unset.
  FallbackInfo fallback_info = 2;
}

// ComputeRouteMatrix request message
message ComputeRouteMatrixRequest {
  // Required. Array of origins, which determines the rows of the response matrix.
  // Several size restrictions apply to the cardinality of origins and
  // destinations:
  //
  // * The number of elements (origins × destinations) must be no greater than
  // 625 in any case.
  // * The number of elements (origins × destinations) must be no greater than
  // 100 if routing_preference is set to `TRAFFIC_AWARE_OPTIMAL`.
  // * The number of waypoints (origins + destinations) specified as `place_id`
  // must be no greater than 50.
  repeated RouteMatrixOrigin origins = 1 [(google.api.field_behavior) = REQUIRED];

  // Required. Array of destinations, which determines the columns of the response matrix.
  repeated RouteMatrixDestination destinations = 2 [(google.api.field_behavior) = REQUIRED];

  // Optional. Specifies the mode of transportation.
  RouteTravelMode travel_mode = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Specifies how to compute the route. The server attempts to use the selected
  // routing preference to compute the route. If the routing preference results
  // in an error or an extra long latency, an error is returned. In the future,
  // we might implement a fallback mechanism to use a different option when the
  // preferred option does not give a valid result. You can specify this option
  // only when the `travel_mode` is `DRIVE` or `TWO_WHEELER`, otherwise the
  // request fails.
  RoutingPreference routing_preference = 4 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The departure time. If you don't set this value, this defaults to the time
  // that you made the request. If you set this value to a time that has already
  // occurred, the request fails.
  google.protobuf.Timestamp departure_time = 5 [(google.api.field_behavior) = OPTIONAL];
}

// A single origin for ComputeRouteMatrixRequest
message RouteMatrixOrigin {
  // Required. Origin waypoint
  Waypoint waypoint = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. Modifiers for every route that takes this as the origin
  RouteModifiers route_modifiers = 2 [(google.api.field_behavior) = OPTIONAL];
}

// A single destination for ComputeRouteMatrixRequest
message RouteMatrixDestination {
  // Required. Destination waypoint
  Waypoint waypoint = 1 [(google.api.field_behavior) = REQUIRED];
}

// Encapsulates route information computed for an origin/destination pair in the
// ComputeRouteMatrix API. This proto can be streamed to the client.
message RouteMatrixElement {
  // Zero-based index of the origin in the request.
  optional int32 origin_index = 1;

  // Zero-based index of the destination in the request.
  optional int32 destination_index = 2;

  // Error status code for this element.
  google.rpc.Status status = 3;

  // Indicates whether the route was found or not. Independent of status.
  RouteMatrixElementCondition condition = 9;

  // The travel distance of the route, in meters.
  int32 distance_meters = 4;

  // The length of time needed to navigate the route. If you set the
  // `routing_preference` to `TRAFFIC_UNAWARE`, then this value is the same as
  // `static_duration`. If you set the `routing_preference` to either
  // `TRAFFIC_AWARE` or `TRAFFIC_AWARE_OPTIMAL`, then this value is calculated
  // taking traffic conditions into account.
  google.protobuf.Duration duration = 5;

  // The duration of traveling through the route without taking traffic
  // conditions into consideration.
  google.protobuf.Duration static_duration = 6;

  // Additional information about the route. For example: restriction
  // information and toll information
  RouteTravelAdvisory travel_advisory = 7;

  // In some cases when the server is not able to compute the route with the
  // given preferences for this particular origin/destination pair, it may
  // fall back to using a different mode of computation. When fallback mode is
  // used, this field contains detailed information about the fallback response.
  // Otherwise this field is unset.
  FallbackInfo fallback_info = 8;
}

// The condition of the route being returned.
enum RouteMatrixElementCondition {
  // Only used when the `status` of the element is not OK.
  ROUTE_MATRIX_ELEMENT_CONDITION_UNSPECIFIED = 0;

  // A route was found, and the corresponding information was filled out for the
  // element.
  ROUTE_EXISTS = 1;

  // No route could be found. Fields containing route information, such as
  // `distance_meters` or `duration`, will not be filled out in the element.
  ROUTE_NOT_FOUND = 2;
}