@googlemaps/places 2.0.0 → 2.1.0

package/README.md

@@ -44,7 +44,7 @@ Google APIs Client Libraries, in [Client Libraries Explained][explained].
 1.  [Select or create a Cloud Platform project][projects].
 1.  [Enable billing for your project][billing].
 1.  [Enable the Places API (New) API][enable_api].
-1.  [Set up authentication with a service account][auth] so you can access the
+1.  [Set up authentication][auth] so you can access the
     API from your local workstation.
 
 ### Installing the client library
@@ -167,4 +167,4 @@ See [LICENSE](https://github.com/googleapis/google-cloud-node/blob/main/LICENSE)
 [projects]: https://console.cloud.google.com/project
 [billing]: https://support.google.com/cloud/answer/6293499#enable-billing
 [enable_api]: https://console.cloud.google.com/flows/enableapi?apiid=places.googleapis.com
-[auth]: https://cloud.google.com/docs/authentication/getting-started
+[auth]: https://cloud.google.com/docs/authentication/external/set-up-adc-local

package/build/protos/google/maps/places/v1/address_descriptor.proto

@@ -0,0 +1,144 @@
+// Copyright 2025 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/type/localized_text.proto";
+
+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 = "AddressDescriptorProto";
+option java_package = "com.google.maps.places.v1";
+option objc_class_prefix = "GMPSV1";
+option php_namespace = "Google\\Maps\\Places\\V1";
+
+// A relational description of a location. Includes a ranked set of nearby
+// landmarks and precise containing areas and their relationship to the target
+// location.
+message AddressDescriptor {
+  // Basic landmark information and the landmark's relationship with the
+  // target location.
+  //
+  // Landmarks are prominent places that can be used to describe a location.
+  message Landmark {
+    // Defines the spatial relationship between the target location and the
+    // landmark.
+    enum SpatialRelationship {
+      // This is the default relationship when nothing more specific below
+      // applies.
+      NEAR = 0;
+
+      // The landmark has a spatial geometry and the target is within its
+      // bounds.
+      WITHIN = 1;
+
+      // The target is directly adjacent to the landmark.
+      BESIDE = 2;
+
+      // The target is directly opposite the landmark on the other side of the
+      // road.
+      ACROSS_THE_ROAD = 3;
+
+      // On the same route as the landmark but not besides or across.
+      DOWN_THE_ROAD = 4;
+
+      // Not on the same route as the landmark but a single turn away.
+      AROUND_THE_CORNER = 5;
+
+      // Close to the landmark's structure but further away from its street
+      // entrances.
+      BEHIND = 6;
+    }
+
+    // The landmark's resource name.
+    string name = 1 [
+      (google.api.resource_reference) = { type: "places.googleapis.com/Place" }
+    ];
+
+    // The landmark's place id.
+    string place_id = 2;
+
+    // The landmark's display name.
+    google.type.LocalizedText display_name = 3;
+
+    // A set of type tags for this landmark. For a complete list of possible
+    // values, see
+    // https://developers.google.com/maps/documentation/places/web-service/place-types.
+    repeated string types = 4;
+
+    // Defines the spatial relationship between the target location and the
+    // landmark.
+    SpatialRelationship spatial_relationship = 5;
+
+    // The straight line distance, in meters, between the center point of the
+    // target and the center point of the landmark. In some situations, this
+    // value can be longer than `travel_distance_meters`.
+    float straight_line_distance_meters = 6;
+
+    // The travel distance, in meters, along the road network from the target to
+    // the landmark, if known. This value does not take into account the mode of
+    // transportation, such as walking, driving, or biking.
+    optional float travel_distance_meters = 7;
+  }
+
+  // Area information and the area's relationship with the target location.
+  //
+  // Areas includes precise sublocality, neighborhoods, and large compounds that
+  // are useful for describing a location.
+  message Area {
+    // Defines the spatial relationship between the target location and the
+    // area.
+    enum Containment {
+      // The containment is unspecified.
+      CONTAINMENT_UNSPECIFIED = 0;
+
+      // The target location is within the area region, close to the
+      // center.
+      WITHIN = 1;
+
+      // The target location is within the area region, close to the edge.
+      OUTSKIRTS = 2;
+
+      // The target location is outside the area region, but close by.
+      NEAR = 3;
+    }
+
+    // The area's resource name.
+    string name = 1 [
+      (google.api.resource_reference) = { type: "places.googleapis.com/Place" }
+    ];
+
+    // The area's place id.
+    string place_id = 2;
+
+    // The area's display name.
+    google.type.LocalizedText display_name = 3;
+
+    // Defines the spatial relationship between the target location and the
+    // area.
+    Containment containment = 4;
+  }
+
+  // A ranked list of nearby landmarks. The most recognizable and nearby
+  // landmarks are ranked first.
+  repeated Landmark landmarks = 1;
+
+  // A ranked list of containing or adjacent areas. The most recognizable and
+  // precise areas are ranked first.
+  repeated Area areas = 2;
+}

package/build/protos/google/maps/places/v1/photo.proto

@@ -50,4 +50,10 @@ message Photo {
 
   // This photo's authors.
   repeated AuthorAttribution author_attributions = 4;
+
+  // A link where users can flag a problem with the photo.
+  string flag_content_uri = 5;
+
+  // A link to show the photo on Google Maps.
+  string google_maps_uri = 6;
 }

package/build/protos/google/maps/places/v1/place.proto

@@ -18,12 +18,12 @@ package google.maps.places.v1;
 
 import "google/api/resource.proto";
 import "google/geo/type/viewport.proto";
+import "google/maps/places/v1/address_descriptor.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/price_range.proto";
-import "google/maps/places/v1/reference.proto";
 import "google/maps/places/v1/review.proto";
 import "google/protobuf/timestamp.proto";
 import "google/type/date.proto";
@@ -177,14 +177,31 @@ message Place {
     optional bool open_now = 1;
 
     // The periods that this place is open during the week. The periods are in
-    // chronological order, starting with Sunday in the place-local timezone. An
-    // empty (but not absent) value indicates a place that is never open, e.g.
+    // chronological order, in the place-local timezone. An empty (but not
+    // absent) value indicates a place that is never open, e.g.
     // because it is closed temporarily for renovations.
+    //
+    // The starting day of `periods` is NOT fixed and should not be assumed to
+    // be Sunday. The API determines the start day based on a variety of
+    // factors. For example, for a 24/7 business, the first period may begin on
+    // the day of the request. For other businesses, it might be the first day
+    // of the week that they are open.
+    //
+    // NOTE: The ordering of the `periods` array is independent of the ordering
+    // of the `weekday_descriptions` array. Do not assume they will begin on the
+    // same day.
     repeated Period periods = 2;
 
     // Localized strings describing the opening hours of this place, one string
-    // for each day of the week.  Will be empty if the hours are unknown or
-    // could not be converted to localized text. Example: "Sun: 18:00–06:00"
+    // for each day of the week.
+    //
+    // NOTE: The order of the days and the start of the week is determined by
+    // the locale (language and region). The ordering of the `periods` array is
+    // independent of the ordering of the `weekday_descriptions` array. Do not
+    // assume they will begin on the same day.
+    //
+    // Will be empty if the hours are unknown or could not be converted to
+    // localized text. Example: "Sun: 18:00–06:00"
     repeated string weekday_descriptions = 3;
 
     // A type string used to identify the type of secondary hours.
@@ -273,15 +290,21 @@ message Place {
     optional bool paid_garage_parking = 7;
   }
 
-  // Place resource name and id of sub destinations that relate to the place.
-  // For example, different terminals are different destinations of an airport.
+  // Sub-destinations are specific places associated with a main place. These
+  // provide more specific destinations for users who are searching within a
+  // large or complex place, like an airport, national park, university, or
+  // stadium. For example, sub-destinations at an airport might include
+  // associated terminals and parking lots. Sub-destinations return the place ID
+  // and place resource name, which can be used in subsequent Place Details
+  // (New) requests to fetch richer details, including the sub-destination's
+  // display name and location.
   message SubDestination {
-    // The resource name of the sub destination.
+    // The resource name of the sub-destination.
     string name = 1 [
       (google.api.resource_reference) = { type: "places.googleapis.com/Place" }
     ];
 
-    // The place id of the sub destination.
+    // The place id of the sub-destination.
     string id = 2;
   }
 
@@ -300,31 +323,18 @@ 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;
+    // A link where users can flag a problem with the overview summary.
+    string overview_flag_content_uri = 4;
 
-    // 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;
+    // The AI disclosure message "Summarized with Gemini"
+    // (and its localized variants). This will be in the language specified in
+    // the request if available.
+    google.type.LocalizedText disclosure_text = 6;
   }
 
   // Info about the place in which this place is located.
@@ -338,6 +348,63 @@ message Place {
     string id = 2;
   }
 
+  // AI-generated summary of the place using user reviews.
+  message ReviewSummary {
+    // The summary of user reviews.
+    google.type.LocalizedText text = 1;
+
+    // A link where users can flag a problem with the summary.
+    string flag_content_uri = 2;
+
+    // The AI disclosure message "Summarized with Gemini"
+    // (and its localized variants). This will be in the language specified in
+    // the request if available.
+    google.type.LocalizedText disclosure_text = 3;
+  }
+
+  // The summary of amenities near the EV charging station. This only applies to
+  // places with type `electric_vehicle_charging_station`. The `overview` field
+  // is guaranteed to be provided while the other fields are optional.
+  message EvChargeAmenitySummary {
+    // An overview of the available amenities. This is guaranteed to be
+    // provided.
+    ContentBlock overview = 1;
+
+    // A summary of the nearby coffee options.
+    ContentBlock coffee = 2;
+
+    // A summary of the nearby restaurants.
+    ContentBlock restaurant = 3;
+
+    // A summary of the nearby gas stations.
+    ContentBlock store = 4;
+
+    // A link where users can flag a problem with the summary.
+    string flag_content_uri = 5;
+
+    // The AI disclosure message "Summarized with Gemini"
+    // (and its localized variants). This will be in the language specified in
+    // the request if available.
+    google.type.LocalizedText disclosure_text = 6;
+  }
+
+  // A summary of points of interest near the place.
+  message NeighborhoodSummary {
+    // An overview summary of the neighborhood.
+    ContentBlock overview = 1;
+
+    // A detailed description of the neighborhood.
+    ContentBlock description = 2;
+
+    // A link where users can flag a problem with the summary.
+    string flag_content_uri = 3;
+
+    // The AI disclosure message "Summarized with Gemini"
+    // (and its localized variants). This will be in the language specified in
+    // the request if available.
+    google.type.LocalizedText disclosure_text = 4;
+  }
+
   // This Place's resource name, in `places/{place_id}` format.  Can be used to
   // look up the Place.
   string name = 1;
@@ -355,17 +422,22 @@ message Place {
   // https://developers.google.com/maps/documentation/places/web-service/place-types
   repeated string types = 5;
 
-  // The primary type of the given result. This type must one of the Places API
-  // supported types. For example, "restaurant", "cafe", "airport", etc.  A
+  // The primary type of the given result. This type must be one of the Places
+  // API supported types. For example, "restaurant", "cafe", "airport", etc.  A
   // place can only have a single primary type.  For the complete list of
   // possible values, see Table A and Table B at
-  // https://developers.google.com/maps/documentation/places/web-service/place-types
+  // https://developers.google.com/maps/documentation/places/web-service/place-types.
+  // The primary type may be missing if the place's primary type is not a
+  // supported type. When a primary type is present, it is always one of the
+  // types in the `types` field.
   string primary_type = 50;
 
   // The display name of the primary type, localized to the request language if
   // applicable. For the complete list of possible values, see Table A and Table
   // B at
-  // https://developers.google.com/maps/documentation/places/web-service/place-types
+  // https://developers.google.com/maps/documentation/places/web-service/place-types.
+  // The primary type may be missing if the place's primary type is not a
+  // supported type.
   google.type.LocalizedText primary_type_display_name = 32;
 
   // A human-readable phone number for the place, in national format.
@@ -429,9 +501,14 @@ message Place {
   // The regular hours of operation. Note that if a place is always open (24
   // hours), the `close` field will not be set. Clients can rely on always open
   // (24 hours) being represented as an
-  // [open][google.maps.places.v1.Place.OpeningHours.Period.open] period
-  // containing [day][Point.day] with value `0`, [hour][Point.hour] with
-  // value `0`, and [minute][Point.minute] with value `0`.
+  // [`open`](https://developers.google.com/maps/documentation/places/web-service/reference/rest/v1/places#Period)
+  // period containing
+  // [`day`](https://developers.google.com/maps/documentation/places/web-service/reference/rest/v1/places#Point)
+  // with value `0`,
+  // [`hour`](https://developers.google.com/maps/documentation/places/web-service/reference/rest/v1/places#Point)
+  // with value `0`, and
+  // [`minute`](https://developers.google.com/maps/documentation/places/web-service/reference/rest/v1/places#Point)
+  // with value `0`.
   OpeningHours regular_opening_hours = 21;
 
   // Number of minutes this place's timezone is currently offset from UTC.
@@ -573,7 +650,7 @@ message Place {
   // Options of parking provided by the place.
   ParkingOptions parking_options = 70;
 
-  // A list of sub destinations related to the place.
+  // A list of sub-destinations related to the place.
   repeated SubDestination sub_destinations = 71;
 
   // Information about the accessibility options a place offers.
@@ -586,20 +663,9 @@ 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;
-
   // List of places in which the current place is located.
   repeated ContainingPlace containing_places = 82;
 
@@ -610,8 +676,23 @@ message Place {
   // have a physical address or location on Google Maps.
   optional bool pure_service_area_business = 83;
 
+  // The address descriptor of the place. Address descriptors include additional
+  // information that help describe a location using landmarks and areas. See
+  // address descriptor regional coverage in
+  // https://developers.google.com/maps/documentation/geocoding/address-descriptors/coverage.
+  AddressDescriptor address_descriptor = 84;
+
   // The price range associated with a Place.
   PriceRange price_range = 86;
+
+  // AI-generated summary of the place using user reviews.
+  ReviewSummary review_summary = 87;
+
+  // The summary of amenities near the EV charging station.
+  EvChargeAmenitySummary ev_charge_amenity_summary = 89;
+
+  // A summary of points of interest near the place.
+  NeighborhoodSummary neighborhood_summary = 91;
 }
 
 // Price level of the place.

package/build/protos/google/maps/places/v1/places_service.proto

@@ -41,9 +41,10 @@ option objc_class_prefix = "GMPSV1";
 option php_namespace = "Google\\Maps\\Places\\V1";
 
 // Service definition for the Places API.
-// Note: every request (except for Autocomplete requests) requires a field mask
-// set outside of the request proto (`all/*`, is not assumed). The field mask
-// can be set via the HTTP header `X-Goog-FieldMask`. See:
+// Note: every request (except for Autocomplete and GetPhotoMedia requests)
+// requires a field mask set outside of the request proto (`all/*`, is not
+// assumed). The field mask can be set via the HTTP header `X-Goog-FieldMask`.
+// See:
 // https://developers.google.com/maps/documentation/places/web-service/choose-fields
 service Places {
   option (google.api.default_host) = "places.googleapis.com";

package/build/protos/google/maps/places/v1/review.proto

@@ -19,6 +19,7 @@ package google.maps.places.v1;
 import "google/api/resource.proto";
 import "google/maps/places/v1/attribution.proto";
 import "google/protobuf/timestamp.proto";
+import "google/type/date.proto";
 import "google/type/localized_text.proto";
 
 option csharp_namespace = "Google.Maps.Places.V1";
@@ -61,4 +62,10 @@ message Review {
 
   // Timestamp for the review.
   google.protobuf.Timestamp publish_time = 14;
+
+  // A link where users can flag a problem with the review.
+  string flag_content_uri = 15;
+
+  // A link to show the review on Google Maps.
+  string google_maps_uri = 16;
 }