feat: Add ExtraComputations feature to ComputeRoutes and ComputeRouteMatrix

packages/google-maps-routing/.jsdoc.js

@@ -1,4 +1,4 @@
-// Copyright 2022 Google LLC
+// Copyright 2023 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -40,7 +40,7 @@ module.exports = {
     includePattern: '\\.js$'
   },
   templates: {
-    copyright: 'Copyright 2022 Google LLC',
+    copyright: 'Copyright 2023 Google LLC',
     includeDate: false,
     sourceFiles: false,
     systemName: '@googlemaps/routing',

packages/google-maps-routing/protos/google/maps/routing/v2/route.proto

@@ -86,6 +86,10 @@ message Route {
   // and in the event of rerouting honor the original intention when Routes
   // ComputeRoutes is called. Customers should treat this token as an
   // opaque blob.
+  // NOTE: `Route.route_token` is only available for requests that have set
+  // `ComputeRoutesRequest.routing_preference` to `TRAFFIC_AWARE` or
+  // `TRAFFIC_AWARE_OPTIMAL`. `Route.route_token` is also not supported for
+  // requests that have Via waypoints.
   string route_token = 12;
 }
 

packages/google-maps-routing/protos/google/maps/routing/v2/route_travel_mode.proto

@@ -27,6 +27,10 @@ option php_namespace = "Google\\Maps\\Routing\\V2";
 option ruby_package = "Google::Maps::Routing::V2";
 
 // A set of values used to specify the mode of travel.
+// NOTE: WALK, BICYCLE, and TWO_WHEELER routes are in beta and might sometimes
+// be missing clear sidewalks, pedestrian paths, or bicycling paths.
+// You must display this warning to the user for all walking, bicycling, and
+// two-wheel routes that you display in your app.
 enum RouteTravelMode {
   // No travel mode specified. Defaults to `DRIVE`.
   TRAVEL_MODE_UNSPECIFIED = 0;

packages/google-maps-routing/protos/google/maps/routing/v2/routes_service.proto

@@ -122,7 +122,8 @@ service Routes {
   // 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) {
+  rpc ComputeRouteMatrix(ComputeRouteMatrixRequest)
+      returns (stream RouteMatrixElement) {
     option (google.api.http) = {
       post: "/distanceMatrix/v2:computeRouteMatrix"
       body: "*"
@@ -142,6 +143,21 @@ message ComputeRoutesRequest {
     FUEL_EFFICIENT = 1;
   }
 
+  // Extra computations to perform while completing the request.
+  enum ExtraComputation {
+    // Not used. Requests containing this value will fail.
+    EXTRA_COMPUTATION_UNSPECIFIED = 0;
+
+    // Toll information for the route(s).
+    TOLLS = 1;
+
+    // Estimated fuel consumption for the route(s).
+    FUEL_CONSUMPTION = 2;
+
+    // Traffic aware polylines for the route(s).
+    TRAFFIC_ON_POLYLINE = 3;
+  }
+
   // Required. Origin waypoint.
   Waypoint origin = 1 [(google.api.field_behavior) = REQUIRED];
 
@@ -159,24 +175,26 @@ message ComputeRoutesRequest {
   // 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];
+  // an error is returned. 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];
+  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];
+  google.protobuf.Timestamp departure_time = 7
+      [(google.api.field_behavior) = OPTIONAL];
 
-  // Optional. Specifies whether to calculate alternate routes in addition to the route.
+  // 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
@@ -198,13 +216,20 @@ message ComputeRoutesRequest {
   // units are inferred from the location of the request.
   Units units = 11 [(google.api.field_behavior) = OPTIONAL];
 
-  // Optional. Specifies what reference routes to calculate as part of the request in
-  // addition to the default route.
-  // A reference route is a route with a different route calculation objective
-  // than the default route. For example an FUEL_EFFICIENT reference route
-  // calculation takes into account various parameters that would generate an
-  // optimal fuel efficient route.
-  repeated ReferenceRoute requested_reference_routes = 14 [(google.api.field_behavior) = OPTIONAL];
+  // Optional. Specifies what reference routes to calculate as part of the
+  // request in addition to the default route. A reference route is a route with
+  // a different route calculation objective than the default route. For example
+  // an FUEL_EFFICIENT reference route calculation takes into account various
+  // parameters that would generate an optimal fuel efficient route.
+  repeated ReferenceRoute requested_reference_routes = 14
+      [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. A list of extra computations which may be used to complete the
+  // request. Note: These extra computations may return extra fields on the
+  // response. These extra fields must also be specified in the field mask to be
+  // returned in the response.
+  repeated ExtraComputation extra_computations = 15
+      [(google.api.field_behavior) = OPTIONAL];
 }
 
 // ComputeRoutes the response message.
@@ -225,8 +250,17 @@ message ComputeRoutesResponse {
 
 // 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
+  // Extra computations to perform while completing the request.
+  enum ExtraComputation {
+    // Not used. Requests containing this value will fail.
+    EXTRA_COMPUTATION_UNSPECIFIED = 0;
+
+    // Toll information for the matrix element(s).
+    TOLLS = 1;
+  }
+
+  // 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
@@ -235,27 +269,37 @@ message ComputeRouteMatrixRequest {
   // 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];
+  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];
+  // 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];
+  // 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. 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];
+
+  // Optional. A list of extra computations which may be used to complete the
+  // request. Note: These extra computations may return extra fields on the
+  // response. These extra fields must also be specified in the field mask to be
+  // returned in the response.
+  repeated ExtraComputation extra_computations = 8
+      [(google.api.field_behavior) = OPTIONAL];
 }
 
 // A single origin for ComputeRouteMatrixRequest