feat: [places] add routing_parameters to SearchNearbyRequest and SearchTextRequest

packages/google-maps-places/protos/google/maps/places/v1/place.proto

@@ -167,8 +167,10 @@ message Place {
       google.type.Date date = 1;
     }
 
-    // Is this place open right now?  Always present unless we lack time-of-day
-    // or timezone data for these opening hours.
+    // Whether the opening hours period is currently active. For regular opening
+    // hours and current opening hours, this field means whether the place is
+    // open. For secondary opening hours and current secondary opening hours,
+    // this field means whether the secondary hours of this place is active.
     optional bool open_now = 1;
 
     // The periods that this place is open during the week. The periods are in

packages/google-maps-places/protos/google/maps/places/v1/places_service.proto

@@ -25,6 +25,11 @@ import "google/maps/places/v1/contextual_content.proto";
 import "google/maps/places/v1/ev_charging.proto";
 import "google/maps/places/v1/geometry.proto";
 import "google/maps/places/v1/place.proto";
+import "google/maps/places/v1/polyline.proto";
+import "google/maps/places/v1/route_modifiers.proto";
+import "google/maps/places/v1/routing_preference.proto";
+import "google/maps/places/v1/routing_summary.proto";
+import "google/maps/places/v1/travel_mode.proto";
 import "google/type/latlng.proto";
 
 option cc_enable_arenas = true;
@@ -87,6 +92,28 @@ service Places {
   }
 }
 
+// Parameters to configure the routing calculations to the places in the
+// response, both along a route (where result ranking will be influenced) and
+// for calculating travel times on results.
+message RoutingParameters {
+  // Optional. An explicit routing origin that overrides the origin defined in
+  // the polyline. By default, the polyline origin is used.
+  google.type.LatLng origin = 1 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. The travel mode.
+  TravelMode travel_mode = 2 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. The route modifiers.
+  RouteModifiers route_modifiers = 3 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. Specifies how to compute the routing summaries. The server
+  // attempts to use the selected routing preference to compute the route. The
+  // traffic aware routing preference is only available for the `DRIVE` or
+  // `TWO_WHEELER` `travelMode`.
+  RoutingPreference routing_preference = 4
+      [(google.api.field_behavior) = OPTIONAL];
+}
+
 // Request proto for Search Nearby.
 //
 //
@@ -222,6 +249,10 @@ message SearchNearbyRequest {
 
   // How results will be ranked in the response.
   RankPreference rank_preference = 9;
+
+  // Optional. Parameters that affect the routing to the search results.
+  RoutingParameters routing_parameters = 10
+      [(google.api.field_behavior) = OPTIONAL];
 }
 
 // Response proto for Search Nearby.
@@ -230,6 +261,13 @@ message SearchNearbyResponse {
   // A list of places that meets user's requirements like places
   // types, number of places and specific location restriction.
   repeated Place places = 1;
+
+  // A list of routing summaries where each entry associates to the
+  // corresponding place in the same index in the places field. If the routing
+  // summary is not available for one of the places, it will contain an empty
+  // entry. This list should have as many entries as the list of places if
+  // requested.
+  repeated RoutingSummary routing_summaries = 2;
 }
 
 // Request proto for SearchText.
@@ -295,6 +333,25 @@ message SearchTextRequest {
         [(google.api.field_behavior) = OPTIONAL];
   }
 
+  // Specifies a precalculated polyline from the [Routes
+  // API](https://developers.google.com/maps/documentation/routes) defining the
+  // route to search. Searching along a route is similar to using the
+  // `locationBias` or `locationRestriction` request option to bias the search
+  // results. However, while the `locationBias` and `locationRestriction`
+  // options let you specify a region to bias the search results, this option
+  // lets you bias the results along a trip route.
+  //
+  // Results are not guaranteed to be along the route provided, but rather are
+  // ranked within the search area defined by the polyline and, optionally, by
+  // the `locationBias` or `locationRestriction` based on minimal detour times
+  // from origin to destination. The results might be along an alternate route,
+  // especially if the provided polyline does not define an optimal route from
+  // origin to destination.
+  message SearchAlongRouteParameters {
+    // Required. The route polyline.
+    Polyline polyline = 1 [(google.api.field_behavior) = REQUIRED];
+  }
+
   // Required. The text query for textual search.
   string text_query = 1 [(google.api.field_behavior) = REQUIRED];
 
@@ -365,6 +422,14 @@ message SearchTextRequest {
 
   // Optional. Set the searchable EV options of a place search request.
   EVOptions ev_options = 15 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. Additional parameters for routing to results.
+  RoutingParameters routing_parameters = 16
+      [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. Additional parameters proto for searching along a route.
+  SearchAlongRouteParameters search_along_route_parameters = 17
+      [(google.api.field_behavior) = OPTIONAL];
 }
 
 // Response proto for SearchText.
@@ -373,6 +438,13 @@ message SearchTextResponse {
   // A list of places that meet the user's text search criteria.
   repeated Place places = 1;
 
+  // A list of routing summaries where each entry associates to the
+  // corresponding place in the same index in the places field. If the routing
+  // summary is not available for one of the places, it will contain an empty
+  // entry. This list will have as many entries as the list of places if
+  // requested.
+  repeated RoutingSummary routing_summaries = 2;
+
   // Experimental: See
   // https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative
   // for more details.
@@ -382,7 +454,7 @@ message SearchTextResponse {
   // that are relevant to the `text_query` in the request are preferred. If the
   // contextual content is not available for one of the places, it will return
   // non-contextual content. It will be empty only when the content is
-  // unavailable for this place. This list should have as many entries as the
+  // unavailable for this place. This list will have as many entries as the
   // list of places if requested.
   repeated ContextualContent contextual_contents = 3;
 }

packages/google-maps-places/protos/google/maps/places/v1/polyline.proto

@@ -0,0 +1,47 @@
+// Copyright 2024 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.places.v1;
+
+option cc_enable_arenas = true;
+option csharp_namespace = "Google.Maps.Places.V1";
+option go_package = "cloud.google.com/go/maps/places/apiv1/placespb;placespb";
+option java_multiple_files = true;
+option java_outer_classname = "PolylineProto";
+option java_package = "com.google.maps.places.v1";
+option objc_class_prefix = "GMPSV1";
+option php_namespace = "Google\\Maps\\Places\\V1";
+
+// A route polyline.  Only supports an [encoded
+// polyline](https://developers.google.com/maps/documentation/utilities/polylinealgorithm),
+// which can be passed as a string and includes compression with minimal
+// lossiness. This is the Routes API default output.
+message Polyline {
+  // Encapsulates the type of polyline. Routes API output defaults to
+  // `encoded_polyline`.
+  oneof polyline_type {
+    // An [encoded
+    // polyline](https://developers.google.com/maps/documentation/utilities/polylinealgorithm),
+    // as returned by the [Routes API by
+    // default](https://developers.google.com/maps/documentation/routes/reference/rest/v2/TopLevel/computeRoutes#polylineencoding).
+    // See the
+    // [encoder](https://developers.google.com/maps/documentation/utilities/polylineutility)
+    // and
+    // [decoder](https://developers.google.com/maps/documentation/routes/polylinedecoder)
+    // tools.
+    string encoded_polyline = 1;
+  }
+}

packages/google-maps-places/protos/google/maps/places/v1/route_modifiers.proto

@@ -0,0 +1,52 @@
+// Copyright 2024 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.places.v1;
+
+import "google/api/field_behavior.proto";
+
+option cc_enable_arenas = true;
+option csharp_namespace = "Google.Maps.Places.V1";
+option go_package = "cloud.google.com/go/maps/places/apiv1/placespb;placespb";
+option java_multiple_files = true;
+option java_outer_classname = "RouteModifiersProto";
+option java_package = "com.google.maps.places.v1";
+option objc_class_prefix = "GMPSV1";
+option php_namespace = "Google\\Maps\\Places\\V1";
+
+// Encapsulates a set of optional conditions to satisfy when calculating the
+// routes.
+message RouteModifiers {
+  // Optional. When set to true, avoids toll roads where reasonable, giving
+  // preference to routes not containing toll roads. Applies only to the `DRIVE`
+  // and `TWO_WHEELER` [`TravelMode`][google.maps.places.v1.TravelMode].
+  bool avoid_tolls = 1 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. When set to true, avoids highways where reasonable, giving
+  // preference to routes not containing highways. Applies only to the `DRIVE`
+  // and `TWO_WHEELER` [`TravelMode`][google.maps.places.v1.TravelMode].
+  bool avoid_highways = 2 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. When set to true, avoids ferries where reasonable, giving
+  // preference to routes not containing ferries. Applies only to the `DRIVE`
+  // and `TWO_WHEELER` [`TravelMode`][google.maps.places.v1.TravelMode].
+  bool avoid_ferries = 3 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. When set to true, avoids navigating indoors where reasonable,
+  // giving preference to routes not containing indoor navigation. Applies only
+  // to the `WALK` [`TravelMode`][google.maps.places.v1.TravelMode].
+  bool avoid_indoor = 4 [(google.api.field_behavior) = OPTIONAL];
+}

packages/google-maps-places/protos/google/maps/places/v1/routing_preference.proto

@@ -0,0 +1,57 @@
+// Copyright 2024 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.places.v1;
+
+option cc_enable_arenas = true;
+option csharp_namespace = "Google.Maps.Places.V1";
+option go_package = "cloud.google.com/go/maps/places/apiv1/placespb;placespb";
+option java_multiple_files = true;
+option java_outer_classname = "RoutingPreferenceProto";
+option java_package = "com.google.maps.places.v1";
+option objc_class_prefix = "GMPSV1";
+option php_namespace = "Google\\Maps\\Places\\V1";
+
+// A set of values that specify factors to take into consideration when
+// calculating the route.
+enum RoutingPreference {
+  // No routing preference specified. Default to `TRAFFIC_UNAWARE`.
+  ROUTING_PREFERENCE_UNSPECIFIED = 0;
+
+  // Computes routes without taking live traffic conditions into consideration.
+  // Suitable when traffic conditions don't matter or are not applicable.
+  // Using this value produces the lowest latency.
+  // Note: For [`TravelMode`][google.maps.places.v1.TravelMode]
+  // `DRIVE` and `TWO_WHEELER`, the route and duration chosen are based on road
+  // network and average time-independent traffic conditions, not current road
+  // conditions. Consequently, routes may include roads that are temporarily
+  // closed. Results for a given
+  // request may vary over time due to changes in the road network, updated
+  // average traffic conditions, and the distributed nature of the service.
+  // Results may also vary between nearly-equivalent routes at any time or
+  // frequency.
+  TRAFFIC_UNAWARE = 1;
+
+  // Calculates routes taking live traffic conditions into consideration.
+  // In contrast to `TRAFFIC_AWARE_OPTIMAL`, some optimizations are applied to
+  // significantly reduce latency.
+  TRAFFIC_AWARE = 2;
+
+  // Calculates the routes taking live traffic conditions into consideration,
+  // without applying most performance optimizations. Using this value produces
+  // the highest latency.
+  TRAFFIC_AWARE_OPTIMAL = 3;
+}

packages/google-maps-places/protos/google/maps/places/v1/routing_summary.proto

@@ -0,0 +1,54 @@
+// Copyright 2024 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.places.v1;
+
+import "google/protobuf/duration.proto";
+
+option cc_enable_arenas = true;
+option csharp_namespace = "Google.Maps.Places.V1";
+option go_package = "cloud.google.com/go/maps/places/apiv1/placespb;placespb";
+option java_multiple_files = true;
+option java_outer_classname = "RoutingSummaryProto";
+option java_package = "com.google.maps.places.v1";
+option objc_class_prefix = "GMPSV1";
+option php_namespace = "Google\\Maps\\Places\\V1";
+
+// The duration and distance from the routing origin to a place in the
+// response, and a second leg from that place to the destination, if requested.
+// Note: Adding `routingSummaries` in the field mask without also including
+// either the `routingParameters.origin` parameter or the
+// `searchAlongRouteParameters.polyline.encodedPolyline` parameter in the
+// request causes an error.
+message RoutingSummary {
+  // A leg is a single portion of a journey from one location to another.
+  message Leg {
+    // The time it takes to complete this leg of the trip.
+    google.protobuf.Duration duration = 1;
+
+    // The distance of this leg of the trip.
+    int32 distance_meters = 2;
+  }
+
+  // The legs of the trip.
+  //
+  // When you calculate travel duration and distance from a set origin, `legs`
+  // contains a single leg containing the duration and distance from the origin
+  // to the destination.  When you do a search along route, `legs` contains two
+  // legs: one from the origin to place, and one from the place to the
+  // destination.
+  repeated Leg legs = 1;
+}