feat: add AutoComplete API

feat: add Searchable EV feature to TextSearch API

PiperOrigin-RevId: 608184544

google/maps/places/v1/place.proto

@@ -283,8 +283,8 @@ message Place {
     optional bool wheelchair_accessible_seating = 4;
   }
 
-  // An ID representing this place which may be used to look up this place
-  // again (a.k.a. the API "resource" name: places/place_id).
+  // This Place's resource name, in `places/{place_id}` format.  Can be used to
+  // look up the Place.
   string name = 1;
 
   // The unique identifier of a place.

google/maps/places/v1/places_service.proto

@@ -21,8 +21,10 @@ 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/ev_charging.proto";
 import "google/maps/places/v1/geometry.proto";
 import "google/maps/places/v1/place.proto";
+import "google/type/latlng.proto";
 
 option cc_enable_arenas = true;
 option csharp_namespace = "Google.Maps.Places.V1";
@@ -66,13 +68,23 @@ service Places {
     option (google.api.method_signature) = "name";
   }
 
-  // Get place details with a place id (in a name) string.
+  // Get the details of a place based on its resource name, which is a string
+  // in the `places/{place_id}` format.
   rpc GetPlace(GetPlaceRequest) returns (Place) {
     option (google.api.http) = {
       get: "/v1/{name=places/*}"
     };
     option (google.api.method_signature) = "name";
   }
+
+  // Returns predictions for the given input.
+  rpc AutocompletePlaces(AutocompletePlacesRequest)
+      returns (AutocompletePlacesResponse) {
+    option (google.api.http) = {
+      post: "/v1/places:autocomplete"
+      body: "*"
+    };
+  }
 }
 
 // Request proto for Search Nearby.
@@ -214,7 +226,6 @@ message SearchNearbyRequest {
 
 // Response proto for Search Nearby.
 //
-//
 message SearchNearbyResponse {
   // A list of places that meets user's requirements like places
   // types, number of places and specific location restriction.
@@ -269,6 +280,19 @@ message SearchTextRequest {
     }
   }
 
+  // Searchable EV options of a place search request.
+  message EVOptions {
+    // Optional. Filtering places by minimum charging rate. Any places with
+    // charging a rate less than the minimum charging rate are filtered out.
+    double minimum_charging_rate_kw = 1
+        [(google.api.field_behavior) = OPTIONAL];
+
+    // Optional. The list of preferred EV connector types. A place that does not
+    // support any of the listed connector types are filter out.
+    repeated EVConnectorType connector_types = 2
+        [(google.api.field_behavior) = OPTIONAL];
+  }
+
   // Required. The text query for textual search.
   string text_query = 1 [(google.api.field_behavior) = REQUIRED];
 
@@ -336,6 +360,9 @@ message SearchTextRequest {
   // results outside given location will not be returned. Cannot be set along
   // with location_bias.
   LocationRestriction location_restriction = 14;
+
+  // Optional. Set the searchable EV options of a place search request.
+  EVOptions ev_options = 15 [(google.api.field_behavior) = OPTIONAL];
 }
 
 // Response proto for SearchText.
@@ -411,11 +438,10 @@ message PhotoMedia {
   string photo_uri = 2;
 }
 
-// Request for fetching a Place with a place id (in a name) string.
+// Request for fetching a Place based on its resource name, which is a string in
+// the `places/{place_id}` format.
 message GetPlaceRequest {
-  // Required. A place ID returned in a Place (with "places/" prefix), or
-  // equivalently the name in the same Place. Format:
-  // `places/{place_id}`.
+  // Required. The resource name of a place, in the `places/{place_id}` format.
   string name = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = { type: "places.googleapis.com/Place" }
@@ -438,4 +464,289 @@ message GetPlaceRequest {
   //
   // Note that 3-digit region codes are not currently supported.
   string region_code = 3 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. An arbitrary string which identifies an autocomplete session for
+  // billing purposes. Must be at most 36 characters in length. Otherwise an
+  // INVALID_ARGUMENT error is returned.
+  //
+  // The session begins when the user starts typing a query, and concludes when
+  // they select a place and a call to Place Details or Address Validation is
+  // made. Each session can have multiple queries, followed by one Place
+  // selection. The credentials used for each request within a session must
+  // belong to the same Google Cloud Console project. Once a session has
+  // concluded, the token is no longer valid; your app must generate a fresh
+  // token for each session. If the `session_token` parameter is omitted, or if
+  // you reuse a session token, the session is charged as if no session token
+  // was provided (each request is billed separately).
+  //
+  // We recommend the following guidelines:
+  // * Use session tokens for all Place Autocomplete calls.
+  // * Generate a fresh token for each session. Using a version 4 UUID is
+  //   recommended.
+  // * Ensure that the credentials used for all Place Autocomplete, Place
+  //   Details, and Address Validation requests within a session belong to the
+  //   same Cloud Console project.
+  // * Be sure to pass a unique session token for each new session. Using the
+  //   same token for more than one session will result in each request being
+  //   billed individually.
+  string session_token = 4 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// Request proto for AutocompletePlaces.
+message AutocompletePlacesRequest {
+  // The region to search. The results may be biased around the specified
+  // region.
+  message LocationBias {
+    oneof type {
+      // A viewport defined by a northeast and a southwest corner.
+      google.geo.type.Viewport rectangle = 1;
+
+      // A circle defined by a center point and radius.
+      Circle circle = 2;
+    }
+  }
+
+  // The region to search. The results will be restricted to the specified
+  // region.
+  message LocationRestriction {
+    oneof type {
+      // A viewport defined by a northeast and a southwest corner.
+      google.geo.type.Viewport rectangle = 1;
+
+      // A circle defined by a center point and radius.
+      Circle circle = 2;
+    }
+  }
+
+  // Required. The text string on which to search.
+  string input = 1 [(google.api.field_behavior) = REQUIRED];
+
+  // Optional. Bias results to a specified location.
+  //
+  // At most one of `location_bias` or `location_restriction` should be set. If
+  // neither are set, the results will be biased by IP address, meaning the IP
+  // address will be mapped to an imprecise location and used as a biasing
+  // signal.
+  LocationBias location_bias = 2 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. Restrict results to a specified location.
+  //
+  // At most one of `location_bias` or `location_restriction` should be set. If
+  // neither are set, the results will be biased by IP address, meaning the IP
+  // address will be mapped to an imprecise location and used as a biasing
+  // signal.
+  LocationRestriction location_restriction = 3
+      [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. Included primary Place type (e.g. "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.
+  repeated string included_primary_types = 4
+      [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. Only include results in the specified regions, specified as up to
+  // 15 CLDR two-character region codes. An empty set will not restrict the
+  // results. If both `location_restriction` and `included_region_codes` are
+  // set, the results will be located in the area of intersection.
+  repeated string included_region_codes = 5
+      [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. The language in which to return results. Defaults to en-US. The
+  // results may be in mixed languages if the language used in `input` is
+  // different from `language_code` or if the returned Place does not have a
+  // translation from the local language to `language_code`.
+  string language_code = 6 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. The region code, specified as a CLDR two-character region code.
+  // This affects address formatting, result ranking, and may influence what
+  // results are returned. This does not restrict results to the specified
+  // region. To restrict results to a region, use `region_code_restriction`.
+  string region_code = 7 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. The origin point from which to calculate geodesic distance to the
+  // destination (returned as `distance_meters`). If this value is omitted,
+  // geodesic distance will not be returned.
+  google.type.LatLng origin = 8 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. A zero-based Unicode character offset of `input` indicating the
+  // cursor position in `input`. The cursor position may influence what
+  // predictions are returned.
+  //
+  // If empty, defaults to the length of `input`.
+  int32 input_offset = 9 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. If true, the response will include both Place and query
+  // predictions. Otherwise the response will only return Place predictions.
+  bool include_query_predictions = 10 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. An arbitrary string which identifies an autocomplete session for
+  // billing purposes. Must be at most 36 characters in length. Otherwise an
+  // INVALID_ARGUMENT error is returned.
+  //
+  // The session begins when the user starts typing a query, and concludes when
+  // they select a place and a call to Place Details or Address Validation is
+  // made. Each session can have multiple queries, followed by one Place
+  // selection. The credentials used for each request within a session must
+  // belong to the same Google Cloud Console project. Once a session has
+  // concluded, the token is no longer valid; your app must generate a fresh
+  // token for each session. If the `session_token` parameter is omitted, or if
+  // you reuse a session token, the session is charged as if no session token
+  // was provided (each request is billed separately).
+  //
+  // We recommend the following guidelines:
+  // * Use session tokens for all Place Autocomplete calls.
+  // * Generate a fresh token for each session. Using a version 4 UUID is
+  //   recommended.
+  // * Ensure that the credentials used for all Place Autocomplete, Place
+  //   Details, and Address Validation requests within a session belong to the
+  //   same Cloud Console project.
+  // * Be sure to pass a unique session token for each new session. Using the
+  //   same token for more than one session will result in each request being
+  //   billed individually.
+  string session_token = 11 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// Response proto for AutocompletePlaces.
+message AutocompletePlacesResponse {
+  // An Autocomplete suggestion result.
+  message Suggestion {
+    // Identifies a substring within a given text.
+    message StringRange {
+      // Zero-based offset of the first Unicode character of the string
+      // (inclusive).
+      int32 start_offset = 1;
+
+      // Zero-based offset of the last Unicode character (exclusive).
+      int32 end_offset = 2;
+    }
+
+    // Text representing a Place or query prediction. The text may be used as is
+    // or formatted.
+    message FormattableText {
+      // Text that may be used as is or formatted with `matches`.
+      string text = 1;
+
+      // A list of string ranges identifying where the input request matched in
+      // `text`. The ranges can be used to format specific parts of `text`. The
+      // substrings may not be exact matches of `input` if the matching was
+      // determined by criteria other than string matching (e.g. spell
+      // corrections or transliterations).
+      //
+      // These values are Unicode character offsets of `text`. The ranges are
+      // guaranteed to be ordered in increasing offset values.
+      repeated StringRange matches = 2;
+    }
+
+    // Contains a breakdown of a Place or query prediction into main text
+    // and secondary text.
+    //
+    // For Place predictions, the main text contains the specific name of the
+    // Place. For query predictions, the main text contains the query.
+    //
+    // The secondary text contains additional disambiguating features (such as a
+    // city or region) to further identify the Place or refine the query.
+    message StructuredFormat {
+      // Represents the name of the Place or query.
+      FormattableText main_text = 1;
+
+      // Represents additional disambiguating features (such as a city or
+      // region) to further identify the Place or refine the query.
+      FormattableText secondary_text = 2;
+    }
+
+    // Prediction results for a Place Autocomplete prediction.
+    message PlacePrediction {
+      // The resource name of the suggested Place. This name can be used in
+      // other APIs that accept Place names.
+      string place = 1 [(google.api.resource_reference) = {
+        type: "places.googleapis.com/Place"
+      }];
+
+      // The unique identifier of the suggested Place. This identifier can be
+      // used in other APIs that accept Place IDs.
+      string place_id = 2;
+
+      // Contains the human-readable name for the returned result. For
+      // establishment results, this is usually the business name and address.
+      //
+      // `text` is recommended for developers who wish to show a single UI
+      // element. Developers who wish to show two separate, but related, UI
+      // elements may want to use `structured_format` instead. They are two
+      // different ways to represent a Place prediction. Users should not try to
+      // parse `structured_format` into `text` or vice versa.
+      //
+      // This text may be different from the `display_name` returned by
+      // GetPlace.
+      //
+      // May be in mixed languages if the request `input` and `language_code`
+      // are in different languages or if the Place does not have a translation
+      // from the local language to `language_code`.
+      FormattableText text = 3;
+
+      // A breakdown of the Place prediction into main text containing the name
+      // of the Place and secondary text containing additional disambiguating
+      // features (such as a city or region).
+      //
+      // `structured_format` is recommended for developers who wish to show two
+      // separate, but related, UI elements. Developers who wish to show a
+      // single UI element may want to use `text` instead. They are two
+      // different ways to represent a Place prediction. Users should not try to
+      // parse `structured_format` into `text` or vice versa.
+      StructuredFormat structured_format = 4;
+
+      // List of types that apply to this Place from Table A or Table B in
+      // https://developers.google.com/maps/documentation/places/web-service/place-types.
+      //
+      // A type is a categorization of a Place. Places with shared types will
+      // share similar characteristics.
+      repeated string types = 5;
+
+      // The length of the geodesic in meters from `origin` if `origin` is
+      // specified. Certain predictions such as routes may not populate this
+      // field.
+      int32 distance_meters = 6;
+    }
+
+    // Prediction results for a Query Autocomplete prediction.
+    message QueryPrediction {
+      // The predicted text. This text does not represent a Place, but rather a
+      // text query that could be used in a search endpoint (e.g. TextSearch).
+      //
+      // `text` is recommended for developers who wish to show a single UI
+      // element. Developers who wish to show two separate, but related, UI
+      // elements may want to use `structured_format` instead. They are two
+      // different ways to represent a query prediction. Users should not try to
+      // parse `structured_format` into `text` or vice versa.
+      //
+      // May be in mixed languages if the request `input` and `language_code`
+      // are in different languages or if part of the query does not have a
+      // translation from the local language to `language_code`.
+      FormattableText text = 1;
+
+      // A breakdown of the query prediction into main text containing the query
+      // and secondary text containing additional disambiguating features (such
+      // as a city or region).
+      //
+      // `structured_format` is recommended for developers who wish to show two
+      // separate, but related, UI elements. Developers who wish to show a
+      // single UI element may want to use `text` instead. They are two
+      // different ways to represent a query prediction. Users should not try to
+      // parse `structured_format` into `text` or vice versa.
+      StructuredFormat structured_format = 2;
+    }
+
+    oneof kind {
+      // A prediction for a Place.
+      PlacePrediction place_prediction = 1;
+
+      // A prediction for a query.
+      QueryPrediction query_prediction = 2;
+    }
+  }
+
+  // Contains a list of suggestions, ordered in descending order of relevance.
+  repeated Suggestion suggestions = 1;
 }