routes/v1/route_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.routes.v1;

import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/maps/routes/v1/compute_custom_routes_request.proto";
import "google/maps/routes/v1/compute_custom_routes_response.proto";
import "google/maps/routes/v1/compute_route_matrix_request.proto";
import "google/maps/routes/v1/compute_routes_request.proto";
import "google/maps/routes/v1/compute_routes_response.proto";
import "google/maps/routes/v1/route_matrix_element.proto";

option cc_enable_arenas = true;
option csharp_namespace = "Google.Maps.Routes.V1";
option go_package = "cloud.google.com/go/maps/routes/apiv1/routespb;routespb";
option java_multiple_files = true;
option java_outer_classname = "RoutesServiceProto";
option java_package = "com.google.maps.routes.v1";
option objc_class_prefix = "GMRS";
option php_namespace = "Google\\Maps\\Routes\\V1";

// The Routes Preferred API.
service RoutesPreferred {
  option (google.api.default_host) = "routespreferred.googleapis.com";
  option (google.api.oauth_scopes) = "https://www.googleapis.com/auth/maps-platform.routespreferred";

  // 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: "/v1: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: "/v1:computeRouteMatrix"
      body: "*"
    };
  }

  // Given a set of terminal and intermediate waypoints, and a route objective,
  // computes the best route for the route objective. Also returns fastest route
  // and shortest route as reference routes.
  //
  // **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 distances, durations, token and toll info:
  //   `X-Goog-FieldMask:
  //   routes.route.distanceMeters,routes.route.duration,routes.token,routes.route.travelAdvisory.tollInfo`
  //
  // Google discourages 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 ComputeCustomRoutes(ComputeCustomRoutesRequest) returns (ComputeCustomRoutesResponse) {
    option (google.api.http) = {
      post: "/v1:computeCustomRoutes"
      body: "*"
    };
  }
}