// 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.
// 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/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/geo/type/viewport.proto";
import "google/maps/places/v1/geometry.proto";
import "google/maps/places/v1/place.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 = "PlacesServiceProto";
option java_package = "com.google.maps.places.v1";
option objc_class_prefix = "GMPSV1";
option php_namespace = "Google\\Maps\\Places\\V1";

// Service definition for the Places API.
service Places {
  option (google.api.default_host) = "places.googleapis.com";

  // Text query based place search.
  rpc SearchText(SearchTextRequest) returns (SearchTextResponse) {
    option (google.api.http) = {
      post: "/v1/Text:search"
      body: "*"
    };
  }
}

// int 32 range. Both min and max are optional. If only min is set, then the
// range only has a lower bound. If only max is set, then range only has an
// upper bound. At least one of min and max must be set. Values are inclusive.
message Int32Range {
  // Lower bound. If unset, behavior is documented on the range field.
  optional int32 min = 1;

  // Upper bound. If unset, behavior is documented on the range field.
  optional int32 max = 2;
}

// Request data structure for SearchText.
message SearchTextRequest {
  // How results will be ranked in the response.
  enum RankPreference {
    // RankPreference value not set. Will default to DISTANCE.
    RANK_PREFERENCE_UNSPECIFIED = 0;

    // Ranks results by distance.
    DISTANCE = 1;

    // Ranks results by relevance. Sort order determined by normal ranking
    // stack. See SortRefinement::RELEVANCE.
    RELEVANCE = 2;
  }

  // The region to search.
  //
  // Deprecated. Use LocationRestriction or LocationBias instead.
  message Location {
    oneof type {
      // A rectangle box defined by northeast and southwest corner.
      google.geo.type.Viewport rectangle = 1;
    }

    // Make location field a strict restriction and filter out POIs outside of
    // the given location. If location type field is unset this field will have
    // no effect.
    bool strict_restriction = 2;
  }

  // The region to search. This location serves as a bias which means results
  // around given location might be returned.
  message LocationBias {
    oneof type {
      // A rectangle box defined by northeast and southwest corner.
      google.geo.type.Viewport rectangle = 1;

      // A circle defined by center point and radius.
      Circle circle = 2;
    }
  }

  // The region to search. This location serves as a restriction which means
  // results outside given location will not be returned.
  message LocationRestriction {
    oneof type {
      // A rectangle box defined by northeast and southwest corner.
      google.geo.type.Viewport rectangle = 1;
    }
  }

  // Required. The text query for textual search.
  string text_query = 1 [(google.api.field_behavior) = REQUIRED];

  // Place details will be displayed with the preferred language if available.
  // If the language code is unspecified or unrecognized, place details of any
  // language may be returned, with a preference for English if such details
  // exist.
  //
  // Current list of supported languages:
  // https://developers.google.com/maps/faq#languagesupport.
  string language_code = 2;

  // The Unicode country/region code (CLDR) of the location where the
  // request is coming from. It is used to display the place details, like
  // region-specific place name, if available.
  //
  // For more information, see
  // http://www.unicode.org/reports/tr35/#unicode_region_subtag.
  //
  //
  // Note that 3-digit region codes are not currently supported.
  string region_code = 3;

  // How results will be ranked in the response.
  RankPreference rank_preference = 4;

  // The region to search. Setting location would usually yields
  // better results. Recommended to set. This location serves as a bias unless
  // strict_restriction is set to true, which turns the location to a strict
  // restriction.
  //
  // Deprecated.  Use LocationRestriction or LocationBias instead.
  Location location = 5 [deprecated = true];

  // The requested place type. Full list of types supported:
  // https://developers.google.com/places/supported_types. Only support one
  // included type.
  string included_type = 6;

  // Used to restrict the search to places that are open at a specific time.
  // open_now marks if a business is currently open.
  bool open_now = 7;

  // [Deprecated!]Used to restrict the search to places that are within a
  // certain price range. This is on a scale of 0 to 4. Set a minimum of 0 or
  // set a maximum of 4 has no effect on the search results. Min price is
  // default to 0 and max price is default to 4. Default value will be used if
  // either min or max is unset.
  Int32Range price_range = 8 [deprecated = true];

  // Filter out results whose average user rating is strictly less than this
  // limit. A valid value must be an float between 0 and 5 (inclusively) at a
  // 0.5 cadence i.e. `[0, 0.5, 1.0, ... , 5.0]` inclusively. This is to keep
  // parity with LocalRefinement_UserRating. The input rating will round up to
  // the nearest 0.5(ceiling). For instance, a rating of 0.6 will eliminate all
  // results with a less than 1.0 rating.
  double min_rating = 9;

  // Maximum number of results to return. It must be between 1 and 20,
  // inclusively. If the number is unset, it falls back to the upper limit. If
  // the number is set to negative or exceeds the upper limit, an
  // INVALID_ARGUMENT error is returned.
  int32 max_result_count = 10;

  // Used to restrict the search to places that are marked as certain price
  // levels. Users can choose any combinations of price levels. Default to
  // select all price levels.
  repeated PriceLevel price_levels = 11;

  // Used to set strict type filtering for included_type. If set to true, only
  // results of the same type will be returned. Default to false.
  bool strict_type_filtering = 12;

  // The region to search. This location serves as a bias which means results
  // around given location might be returned. Cannot be set along with
  // location_restriction.
  LocationBias location_bias = 13;

  // The region to search. This location serves as a restriction which means
  // results outside given location will not be returned. Cannot be set along
  // with location_bias.
  LocationRestriction location_restriction = 14;
}

// Response proto for SearchText.
//
message SearchTextResponse {
  // A list of places that meet the user's text search criteria.
  repeated Place places = 1;
}