feat: [places] add generative_summary and area_summary for place summaries

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

@@ -0,0 +1,45 @@
+// 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/maps/places/v1/reference.proto";
+import "google/type/localized_text.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 = "ContentBlockProto";
+option java_package = "com.google.maps.places.v1";
+option objc_class_prefix = "GMPSV1";
+option php_namespace = "Google\\Maps\\Places\\V1";
+
+// A block of content that can be served individually.
+message ContentBlock {
+  // The topic of the content, for example "overview" or "restaurant".
+  string topic = 1;
+
+  // Content related to the topic.
+  google.type.LocalizedText content = 2;
+
+  // Experimental: See
+  // https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative
+  // for more details.
+  //
+  // References that are related to this block of content.
+  References references = 3;
+}

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

@@ -0,0 +1,120 @@
+// 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/maps/places/v1/photo.proto";
+import "google/maps/places/v1/review.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 = "ContextualContentProto";
+option java_package = "com.google.maps.places.v1";
+option objc_class_prefix = "GMPSV1";
+option php_namespace = "Google\\Maps\\Places\\V1";
+
+// Experimental: See
+// https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative
+// for more details.
+//
+// Content that is contextual to the place query.
+message ContextualContent {
+  // Experimental: See
+  // https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative
+  // for more details.
+  //
+  // Justifications for the place. Justifications answers the question of why a
+  // place could interest an end user.
+  message Justification {
+    // Experimental: See
+    // https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative
+    // for more details.
+    //
+    // User review justifications. This highlights a section of the user review
+    // that would interest an end user. For instance, if the search query is
+    // "firewood pizza", the review justification highlights the text relevant
+    // to the search query.
+    message ReviewJustification {
+      // The text highlighted by the justification. This is a subset of the
+      // review itself. The exact word to highlight is marked by the
+      // HighlightedTextRange. There could be several words in the text being
+      // highlighted.
+      message HighlightedText {
+        // The range of highlighted text.
+        message HighlightedTextRange {
+          int32 start_index = 1;
+
+          int32 end_index = 2;
+        }
+
+        string text = 1;
+
+        // The list of the ranges of the highlighted text.
+        repeated HighlightedTextRange highlighted_text_ranges = 2;
+      }
+
+      HighlightedText highlighted_text = 1;
+
+      // The review that the highlighted text is generated from.
+      Review review = 2;
+    }
+
+    // Experimental: See
+    // https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative
+    // for more details.
+    // BusinessAvailabilityAttributes justifications. This shows some attributes
+    // a business has that could interest an end user.
+    message BusinessAvailabilityAttributesJustification {
+      // If a place provides takeout.
+      bool takeout = 1;
+
+      // If a place provides delivery.
+      bool delivery = 2;
+
+      // If a place provides dine-in.
+      bool dine_in = 3;
+    }
+
+    oneof justification {
+      // Experimental: See
+      // https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative
+      // for more details.
+      ReviewJustification review_justification = 1;
+
+      // Experimental: See
+      // https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative
+      // for more details.
+      BusinessAvailabilityAttributesJustification
+          business_availability_attributes_justification = 2;
+    }
+  }
+
+  // List of reviews about this place, contexual to the place query.
+  repeated Review reviews = 1;
+
+  // Information (including references) about photos of this place, contexual to
+  // the place query.
+  repeated Photo photos = 2;
+
+  // Experimental: See
+  // https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative
+  // for more details.
+  //
+  // Justifications for the place.
+  repeated Justification justifications = 3;
+}

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

@@ -18,9 +18,11 @@ package google.maps.places.v1;
 
 import "google/api/resource.proto";
 import "google/geo/type/viewport.proto";
+import "google/maps/places/v1/content_block.proto";
 import "google/maps/places/v1/ev_charging.proto";
 import "google/maps/places/v1/fuel_options.proto";
 import "google/maps/places/v1/photo.proto";
+import "google/maps/places/v1/reference.proto";
 import "google/maps/places/v1/review.proto";
 import "google/type/date.proto";
 import "google/type/latlng.proto";
@@ -283,6 +285,33 @@ message Place {
     optional bool wheelchair_accessible_seating = 4;
   }
 
+  // Experimental: See
+  // https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative
+  // for more details.
+  //
+  // AI-generated summary of the place.
+  message GenerativeSummary {
+    // The overview of the place.
+    google.type.LocalizedText overview = 1;
+
+    // The detailed description of the place.
+    google.type.LocalizedText description = 2;
+
+    // References that are used to generate the summary description.
+    References references = 3;
+  }
+
+  // Experimental: See
+  // https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative
+  // for more details.
+  //
+  // AI-generated summary of the area that the place is in.
+  message AreaSummary {
+    // Content blocks that compose the area summary. Each block has a separate
+    // topic about the area.
+    repeated ContentBlock content_blocks = 4;
+  }
+
   // This Place's resource name, in `places/{place_id}` format.  Can be used to
   // look up the Place.
   string name = 1;
@@ -517,6 +546,20 @@ message Place {
 
   // Information of ev charging options.
   EVChargeOptions ev_charge_options = 79;
+
+  // Experimental: See
+  // https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative
+  // for more details.
+  //
+  // AI-generated summary of the place.
+  GenerativeSummary generative_summary = 80;
+
+  // Experimental: See
+  // https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative
+  // for more details.
+  //
+  // AI-generated summary of the area that the place is in.
+  AreaSummary area_summary = 81;
 }
 
 // Price level of the place.

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

@@ -21,6 +21,7 @@ import "google/api/client.proto";
 import "google/api/field_behavior.proto";
 import "google/api/resource.proto";
 import "google/geo/type/viewport.proto";
+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";
@@ -371,6 +372,19 @@ message SearchTextRequest {
 message SearchTextResponse {
   // A list of places that meet the user's text search criteria.
   repeated Place places = 1;
+
+  // Experimental: See
+  // https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative
+  // for more details.
+  //
+  // A list of contextual contents where each entry associates to the
+  // corresponding place in the same index in the places field. The contents
+  // 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
+  // list of places if requested.
+  repeated ContextualContent contextual_contents = 3;
 }
 
 // Request for fetching a photo of a place using a photo resource name.
@@ -542,11 +556,11 @@ message AutocompletePlacesRequest {
       [(google.api.field_behavior) = OPTIONAL];
 
   // Optional. Included primary Place type (for example, "restaurant" or
-  // "gas_station") from
-  // https://developers.google.com/maps/documentation/places/web-service/place-types.
-  // A Place is only returned if its primary type is included in this list. Up
-  // to 5 values can be specified. If no types are specified, all Place types
-  // are returned.
+  // "gas_station") in Place Types
+  // (https://developers.google.com/maps/documentation/places/web-service/place-types),
+  // or only `(regions)`, or only `(cities)`. A Place is only returned if its
+  // primary type is included in this list. Up to 5 values can be specified. If
+  // no types are specified, all Place types are returned.
   repeated string included_primary_types = 4
       [(google.api.field_behavior) = OPTIONAL];
 

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

@@ -0,0 +1,45 @@
+// 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/resource.proto";
+import "google/maps/places/v1/review.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 = "ReferenceProto";
+option java_package = "com.google.maps.places.v1";
+option objc_class_prefix = "GMPSV1";
+option php_namespace = "Google\\Maps\\Places\\V1";
+
+// Experimental: See
+// https://developers.google.com/maps/documentation/places/web-service/experimental/places-generative
+// for more details.
+//
+// Reference that the generative content is related to.
+message References {
+  // Reviews that serve as references.
+  repeated Review reviews = 1;
+
+  // The list of resource names of the referenced places. This name can be used
+  // in other APIs that accept Place resource names.
+  repeated string places = 2 [
+    (google.api.resource_reference) = { type: "places.googleapis.com/Place" }
+  ];
+}