Автозаполнение мест (новая версия)

Сервис Autocomplete (New) – это API для iOS, который возвращает подсказки мест в ответ на запрос. В запросе укажите строку текстового поиска и географические границы, определяющие область поиска.

Сервис Autocomplete (New) может обрабатывать полные слова и их части, предлагая подходящие названия мест, адреса и коды Plus Code. Приложения могут передавать запросы по мере их ввода и сразу же предлагать похожие варианты.

Подсказки мест – это места, например компании, адреса и объекты инфраструктуры, которые подбираются на основе указанной текстовой строки и области поиска.

Например, вы вызываете API, используя в качестве входных данных строку, которая содержит часть введенного пользователем текста, "Spagh", с областью поиска, ограниченной Нью-Йорком. В ответе будет содержаться список подсказок мест, соответствующих поисковому запросу и области поиска, например ресторан "Кафе Спагетти", а также подробные сведения о месте.

Возвращенные подсказки мест предназначены для показа пользователю, чтобы он мог выбрать нужное место. Чтобы получить подробную информацию о любом из них, можно отправить запрос Place Details (New).

Интегрировать функцию автозаполнения (новую) в приложение можно двумя основными способами:

• Получение подсказок мест программными средствами. Вы можете вызывать API напрямую, чтобы получать подсказки и показывать их в собственном пользовательском интерфейсе.
• Добавьте виджет автозаполнения мест. Он позволяет показывать подсказки по мере ввода текста.

Как программно получить подсказки мест

Запросы к Autocomplete (New)

Создайте запрос автозаполнения, вызвав метод в GMSPlacesClient. Параметры можно передавать в объекте GMSAutocompleteRequest. Ответ содержит подсказки автозаполнения в объекте GMSAutocompletePlaceSuggestion.

Ключ API и параметры query являются обязательными. Вы также можете включить GMSAutocompleteSessionToken, чтобы связать запросы с платежным сеансом, и GMSAutocompleteFilter, чтобы применить к результатам.

Подробную информацию об обязательных и дополнительных параметрах можно найти в разделе, посвященном параметрам.

let center = (37.3913916, -122.0879074)
let northEast = (37.388162, -122.088137)
let southWest = (37.395804, -122.077023)

let bias = RectangularCoordinateRegion(northEast: northEast, southWest: southWest)
let filter = AutocompleteFilter(types: [ .restaurant ], origin: center, coordinateRegionBias: bias)

let autocompleteRequest = AutocompleteRequest(query: "Sicilian piz", filter: filter)
switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) {
case .success(let autocompleteSuggestions):
  // Handle suggestions.
case .failure(let placesError):
  // Handle error.
}

let token = GMSAutocompleteSessionToken()

let northWestBounds = CLLocationCoordinate2DMake(40.921628, -73.700051)
let southEastBounds = CLLocationCoordinate2DMake(40.477398, -74.259087)

let filter = GMSAutocompleteFilter()
filter.types = [kGMSPlaceTypeRestaurant]
filter.locationBias = GMSPlaceRectangularLocationOption(northWestBounds, southEastBounds)

let request = GMSAutocompleteRequest(query:"Spagh")
request.filter = filter
request.sessionToken = token

GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { ( results, error ) in
      if let error = error {
        print("Autocomplete error: \(error)")
        return
      }
      if let autocompleteResults = results {
        for result in autocompleteResults {
          print("Result \(String(describing: result.placeSuggestion?.placeID)) with \(String(describing: result.placeSuggestion?.attributedFullText))")
        }
      }
    })

CLLocationCoordinate2D northEast = CLLocationCoordinate2DMake(37.388162, -122.088137);
CLLocationCoordinate2D southWest = CLLocationCoordinate2DMake(37.395804, -122.077023);

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.types = @[ kGMSPlaceTypeRestaurant ];
filter.locationBias = GMSPlaceRectangularLocationOption(northEast, southWest);
GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Sicilian piz"];
request.sessionToken = token;
request.filter = filter;

[[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){
  // Handle response
  for (GMSAutocompleteSuggestion *suggestion in results) {
    if (suggestion.placeSuggestion) {
      // Show place suggestion data.
    }
  }
}];

Ответы Autocomplete (New)

Автозаполнение возвращает массив, содержащий до пяти экземпляров GMSAutocompleteSuggestion. Массив содержит:

• placeID
• types – типы, применимые к этому месту.
• distanceMeters – расстояние от начальной точки.
• attributedFullText – полный человекочитаемый текст подсказки.
• attributedPrimaryText – человекочитаемый основной текст подсказки.
• attributedSecondaryText – человекочитаемый дополнительный текст подсказки.
• structuredFormat – название и уточняющий текст, например город или регион.

Обязательные параметры

запрос

Текстовая строка, по которой выполняется поиск. Укажите полные слова и их части, названия мест, адреса и коды Plus Code. На основе этой строки сервис Autocomplete (New) возвращает список подходящих мест, упорядоченных по их предполагаемой релевантности.

Необязательные параметры

sessionToken

Токены сеансов – это создаваемые пользователем строки, которые отслеживают вызовы Autocomplete (New) (как через виджет, так и программные) как сеансы. Autocomplete (New) использует токены сеансов, чтобы сгруппировать этапы запроса и выбора выполняемого пользователем поиска с функцией автозаполнения в отдельный сеанс для выставления счетов.

Вы можете сделать токен сеанса Places Autocomplete доступным, чтобы передавать его другим сервисам, которые не входят в Places SDK для iOS, например Address Validation.

let token = AutocompleteSessionToken()
let filter = AutocompleteFilter(origin: CLLocationCoordinate2DMake(39.7, -94.5))
let request = AutocompleteRequest(query: "Piz", sessionToken: token, filter: filter)

PlacesClient.shared.fetchAutocompleteSuggestions(request: request) {
    case .success(let suggestions):
      ...
    case .failure(let placesError):
      print(placesError) 
}

// pass token's string format to use with a service that is not a part of iOS SDK.
print("token: \(token)")

GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Piz"];
GMSAutocompleteSessionToken *token = [[GMSAutocompleteSessionToken alloc] init];
request.sessionToken = token;

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.origin = [[CLLocation alloc] initWithLatitude:39.7 longitude:-94.5];
filter.locationBias = GMSPlaceRectangularLocationOption(topLocation, bottomLocation);

request.filter = filter;
 [[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request
                     callback:^(NSArray<GMSAutocompleteSuggestion *> *_Nullable results,
                                NSError *_Nullable error) {
  ...
}];

// pass token's string format to use with a service that is not a part of iOS SDK.
NSLog(@"%@", token.description);

Подробнее о токенах сеансов…

Необязательные параметры AutocompleteFilter

типы

У места может быть только один основной тип из таблицы A или таблицы B. Например, основным типом может быть mexican_restaurant или steak_house.

По умолчанию API возвращает все места на основе параметра input, независимо от значения основного типа, связанного с местом. Чтобы ограничить результаты определенным основным типом или типами, передайте параметр types.

С помощью этого параметра можно указать до пяти значений типа из таблицы A или таблицы B. Чтобы место было включено в ответ, оно должно соответствовать одному из указанных значений основного типа.

Запрос отклоняется с ошибкой INVALID_REQUEST, если:

• Указано более пяти типов.
• указать неизвестный тип;

Например, чтобы ограничить результаты магазинами спортивных товаров, укажите этот тип в AutocompleteFilter:

let filter = AutocompleteFilter(types: [ PlaceType(rawValue: "sporting_goods_store") ])
  

let filter = GMSAutocompleteFilter()
filter.types = ["sporting_goods_store"]
  

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.types = @[ "sporting_goods_store" ];

страны

Включать в результаты только места из указанных регионов. Регионы задаются в виде массива, содержащего до 15 двухсимвольных кодов ccTLD («домен верхнего уровня»). Если этот параметр не указан, к ответу не применяются никакие ограничения. Например, чтобы ограничить регионы Германией и Францией:

let filter = AutocompleteFilter(countries: ["DE", "FR"])
  

let filter = GMSAutocompleteFilter()
filter.countries = ["DE", "FR"]

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.countries = @[ @"DE", @"FR" ];

Если вы укажете и locationRestriction, и countries, результаты будут находиться в области пересечения двух настроек.

inputOffset

Смещение символа Юникода, начинающееся с нуля, которое указывает на положение курсора в input. Положение курсора может влиять на возвращаемые подсказки. Если значение не указано, по умолчанию используется длина input.

locationBias или locationRestriction;

Чтобы определить область поиска, можно указать locationBias или locationRestriction, но не оба параметра. Параметр locationRestriction указывает регион, в котором должны находиться результаты, а параметр locationBias – регион, рядом с которым должны находиться результаты, но они могут быть и за его пределами.

• locationBias – задает область поиска. Это местоположение служит смещением, то есть могут возвращаться результаты в указанном местоположении, в том числе за пределами указанной области.

• locationRestriction – задает область поиска. Результаты за пределами указанной области не возвращаются.

Укажите регион locationBias или locationRestriction в виде прямоугольной области просмотра или круга.

Круг определяется центральной точкой и радиусом в метрах. Радиус должен быть в диапазоне от 0,0 до 50 000,0 включительно. Значение по умолчанию – 0.0. Для locationRestriction необходимо задать радиус больше 0,0. В противном случае запрос не вернет результатов.

Пример:

let center = CLLocationCoordinate2DMake(40.477398, -74.259087)

let bias = CircularCoordinateRegion(center: center, radius: 1000.0)

let filter = AutocompleteFilter(coordinateRegionBias: bias)
  

let center = CLLocationCoordinate2DMake(40.730610, -73.935242)
let radius = 1000.0

filter.locationBias = GMSPlaceCircularLocationOption(center, radius)

CLLocationCoordinate2D center = CLLocationCoordinate2DMake(40.730610, -73.935242);
radius = 1000.0;

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.locationBias = GMSPlaceCircularLocationOption(center, radius);

Прямоугольник – это область просмотра, заданная координатами широты и долготы и представленная двумя противоположными по диагонали точками low и high. Область просмотра считается замкнутым регионом, то есть включает в себя свою границу. Широта должна находиться в диапазоне от -90 до 90 градусов включительно, а долгота – от -180 до 180 градусов включительно.

• Если low = high, область просмотра состоит из одной точки.
• Если low.longitude > high.longitude, диапазон долготы инвертируется (область просмотра пересекает линию долготы 180 градусов).
• Если low.longitude = -180 градусов, а high.longitude= 180 градусов, область просмотра включает все долготы.
• Если low.longitude = 180 градусов, а high.longitude = -180 градусов, диапазон долготы пуст.

Оба поля (low и high) должны быть заполнены, а представленная область не может быть пустой. Если область просмотра пуста, возникает ошибка.

Например, эта область просмотра полностью охватывает Нью-Йорк:

let northEast = CLLocationCoordinate2DMake(40.477398, -74.259087)
let southWest = CLLocationCoordinate2DMake(40.921628, -73.700051)

let filter = AutocompleteFilter(coordinateRegionBias: bias)
  

let high = CLLocationCoordinate2DMake(40.921628, -73.700051)
let low = CLLocationCoordinate2DMake(40.477398, -74.259087)

let filter = GMSAutocompleteFilter()
filter.locationBias = GMSPlaceRectangularLocationOption(high, low)

CLLocationCoordinate2D high = CLLocationCoordinate2DMake(40.477398, -74.259087);
CLLocationCoordinate2D low = CLLocationCoordinate2DMake(440.921628, -73.700051);

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.locationBias = GMSPlaceRectangularLocationOption(high, low);

происхождение

Начальная точка, от которой рассчитывается расстояние по прямой до пункта назначения (возвращается как distanceMeters). Если это значение не указано, расстояние по прямой не возвращается. Указывается в виде координат широты и долготы:

let filter = AutocompleteFilter(origin: CLLocation(latitude: 37.395804, longitude: -122.077023))
  

let filter = GMSAutocompleteFilter()
filter.origin =  CLLocation(latitude: 37.395804, longitude: -122.077023)
 

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];

filter.origin = [[CLLocation alloc] initWithLatitude:37.395804 longitude: -122.077023];

regionCode

Код региона, используемый для форматирования ответа, указывается в виде двухсимвольного значения ccTLD ("домен верхнего уровня"). Большинство кодов ccTLD совпадают с кодами ISO 3166-1, однако имеются некоторые исключения. Например, ccTLD Великобритании – uk (.co.uk), а код ISO 3166-1 – gb (технически для Соединенного Королевства Великобритании и Северной Ирландии).

Если вы укажете неверный код региона, API вернет ошибку INVALID_ARGUMENT. Параметр может влиять на результаты в соответствии с действующим законодательством.

shouldIncludePureServiceAreaBusinesses

Если задано значение true, в массиве ответа возвращаются только компании, обслуживающие определенную территорию. Компания, обслуживающая определенную территорию, осуществляет услуги и доставку не по своему адресу компании, а по адресу клиентов.

Пример:

let filter = AutocompleteFilter()
filter.shouldIncludePureServiceAreaBusinesses = true

let filter = AutocompleteFilter()
filter.shouldIncludePureServiceAreaBusinesses = true

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.shouldIncludePureServiceAreaBusinesses = YES;

Добавление виджета автозаполнения мест

Чтобы упростить работу с автозаполнением мест, вы можете добавить в приложение виджет Place Autocomplete. Он предоставляет полноэкранный интерфейс, который обрабатывает пользовательский ввод и показывает подсказки мест, возвращая в приложение объекты AutocompletePlaceSuggestion. Затем вы можете выполнить запрос Place Details (New), чтобы получить дополнительную информацию о любом из предложенных мест.

Как и при программном получении подсказок мест, виджет автозаполнения мест позволяет использовать токены сеансов, чтобы группировать запросы автозаполнения в сеансы для выставления счетов. Вы можете передать токен сеанса, вызвав AutocompleteSessionToken().

Если вы не укажете токен сеанса, виджет создаст для вас токен сеанса автозаполнения, который затем можно будет получить из обратного вызова onSelection. Подробнее о токенах сеансов…

Если для привязки show задано значение true, пользователь перейдет в полноэкранный режим, где сможет выбрать место. По мере ввода текста виджет предлагает варианты мест, например компаний, адресов и достопримечательностей. Когда пользователь выбирает место, виджет вызывает обработчик onSelection с выбранным местом и закрывает полноэкранный режим.

Параметры виджета автозаполнения мест

Помимо параметров, доступных программно, виджет автозаполнения мест также предлагает следующие параметры.

Показывать

show указывает, показывается ли виджет.

onSelection

Замыкание, которое выполняется при выборе места.

onError

Замыкание, которое выполняется при возникновении ошибки. Если произойдет ошибка, будет передан объект PlacesError.

Настройка контента и темы

Параметры AutocompleteUICustomization определяют настройки интерфейса, которые будут применены к виджету. Доступны следующие варианты настройки:

• AutocompleteListDensity. Этот параметр позволяет выбрать плотность списка подсказок: multiLine или twoLine.
• AutocompleteUIIcon. Этот параметр позволяет выбрать, нужно ли показывать значок по умолчанию для каждого элемента списка.
• theme. Этот параметр задает пользовательскую тему, которая переопределяет любые атрибуты стиля по умолчанию. Вы можете настроить цвета, типографику, интервалы, границы и углы компонента автозаполнения мест. Значение по умолчанию – PlacesMaterialTheme. Для всех атрибутов темы, которые не переопределены, используются стили по умолчанию.

Ознакомьтесь с полным примером кода.

Примеры использования новой версии Autocomplete

Используйте locationRestriction и locationBias

По умолчанию в Autocomplete (New) для управления областью поиска используется смещение по IP-адресу. При смещении по IP-адресу API использует IP-адрес устройства для смещения результатов. Чтобы указать область поиска, можно использовать locationRestriction или locationBias, но не оба параметра одновременно.

Ограничение местоположений определяет область поиска. Результаты за пределами указанной области не возвращаются. В примере ниже ограничение местоположения используется, чтобы ограничить запрос круглой областью радиусом 5000 м с центром в Сан-Франциско.

let center = (37.775061, -122.419400)
let radius = 5000.0
let restriction = CircularCoordinateRegion(center: center, radius: radius)
let filter = AutocompleteFilter(coordinateRegionRestriction: restriction)
let token = AutocompleteSessionToken()

let autocompleteRequest = AutocompleteRequest(query: "Sicilian piz", sessionToken: token, filter: filter)
switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) {
case .success(let autocompleteSuggestions):
  for suggestion in autocompleteSuggestions {
    switch suggestion {
    case .place:
      // Show place suggestion data.
    }
  }
case .failure(let placesError):
  // Handle error.
}
  

let token = GMSAutocompleteSessionToken()

let center = CLLocationCoordinate2DMake(37.775061, -122.419400)
let radius = 5000.0

let filter = GMSAutocompleteFilter()
filter.locationRestriction = GMSPlaceCircularLocationOption(center, radius)

let request = GMSAutocompleteRequest(query:"Piz")
request.filter = filter
request.sessionToken = token

GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { ( results, error ) in
      if let error = error {
        print("Autocomplete error: \(error)")
        return
      }
      if let autocompleteResults = results {
        for result in autocompleteResults {
          print("Result \(String(describing: result.placeSuggestion?.placeID)) with \(String(describing: result.placeSuggestion?.attributedFullText))")
        }
      }
    })

CLLocationCoordinate2D center = CLLocationCoordinate2DMake(37.775061, -122.419400);
radius = 5000.0;

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.locationRestriction = GMSPlaceCircularLocationOption(center, radius);
GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Sicilian piz"];
request.sessionToken = token;
request.filter = filter;

[[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){
  // Handle response
  for (GMSAutocompleteSuggestion *suggestion in results) {
    if (suggestion.placeSuggestion) {
      // Show place suggestion data.
    }
  }
}];

При смещении по местоположению местоположение служит смещением, то есть могут возвращаться результаты вокруг указанного местоположения, в том числе результаты за пределами указанной области. В следующем примере предыдущий запрос изменен для использования смещения местоположения:

let center = (37.775061, -122.419400)
let radius = 5000.0
let bias = CircularCoordinateRegion(center: center, radius: radius)
let filter = AutocompleteFilter(coordinateRegionBias: bias)
let token = AutocompleteSessionToken()

let autocompleteRequest = AutocompleteRequest(query: "Sicilian piz", sessionToken: token, filter: filter)
switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) {
case .success(let autocompleteSuggestions):
  for suggestion in autocompleteSuggestions {
    switch suggestion {
    case .place:
      // Show place suggestion data.
    }
  }
case .failure(let placesError):
  // Handle error.
}
  

let token = GMSAutocompleteSessionToken()

let center = CLLocationCoordinate2DMake(37.775061, -122.419400)
let radius = 5000.0

let filter = GMSAutocompleteFilter()
filter.locationBias = GMSPlaceCircularLocationOption(center, radius)

let request = GMSAutocompleteRequest(query:"Piz")
request.filter = filter
request.sessionToken = token

GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { ( results, error ) in
      if let error = error {
        print("Autocomplete error: \(error)")
        return
      }
      if let autocompleteResults = results {
        for result in autocompleteResults {
          print("Result \(String(describing: result.placeSuggestion?.placeID)) with \(String(describing: result.placeSuggestion?.attributedFullText))")
        }
      }
    })

CLLocationCoordinate2D center = CLLocationCoordinate2DMake(37.775061, -122.419400);
radius = 5000.0;

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.locationBias = GMSPlaceCircularLocationOption(center, radius);
GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Sicilian piz"];
request.sessionToken = token;
request.filter = filter;

[[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){
  // Handle response
  for (GMSAutocompleteSuggestion *suggestion in results) {
    if (suggestion.placeSuggestion) {
      // Show place suggestion data.
    }
  }
}];

Типы использования

Используйте параметр types, чтобы ограничить результаты запроса определенным типом, как указано в таблице A и таблице B. Вы можете указать массив, содержащий до пяти значений. Если его не указать, будут возвращены все типы.

В примере ниже указана строка запроса "Soccer" и используется параметр types, чтобы ограничить результаты заведениями типа "sporting_goods_store".

let filter = AutocompleteFilter(types: [ PlaceType(rawValue: "sporting_goods_store") ])
let token = AutocompleteSessionToken()

let autocompleteRequest = AutocompleteRequest(query: "Soccer", sessionToken: token, filter: filter)
switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) {
case .success(let autocompleteSuggestions):
  for suggestion in autocompleteSuggestions {
    switch suggestion {
    case .place:
      // Show place suggestion data.
    }
  }
case .failure(let placesError):
  // Handle error.
}
    

let token = GMSAutocompleteSessionToken()

let filter = GMSAutocompleteFilter()
filter.types = ["sporting_goods_store"]

let request = GMSAutocompleteRequest(query:"Soccer")
request.filter = filter
request.sessionToken = token

GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { ( results, error ) in
      if let error = error {
        print("Autocomplete error: \(error)")
        return
      }
      if let autocompleteResults = results {
        for result in autocompleteResults {
          print("Result \(String(describing: result.placeSuggestion?.placeID)) with \(String(describing: result.placeSuggestion?.attributedFullText))")
        }
      }
    })

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.types = @[ "sporting_goods_store" ];
GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Soccer"];
request.sessionToken = token;
request.filter = filter;

[[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){
  // Handle response
  for (GMSAutocompleteSuggestion *suggestion in results) {
    if (suggestion.placeSuggestion) {
      // Show place suggestion data.
    }
  }
}];

Использовать источник

Если вы включите в запрос параметр origin, указанный в виде координат широты и долготы, API включит в ответ расстояние по прямой от пункта отправления до пункта назначения. В ответе расстояние возвращается в виде distanceMeters.

В этом примере в качестве начальной точки задан центр Сан-Франциско:

let filter = AutocompleteFilter(origin: CLLocation(latitude: 37.7749, longitude: -122.4194))
let token = AutocompleteSessionToken()

let autocompleteRequest = AutocompleteRequest(query: "Amoeba", sessionToken: token, filter: filter)
switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) {
case .success(let autocompleteSuggestions):
  for suggestion in autocompleteSuggestions {
    switch suggestion {
    case .place:
      // Show place suggestion data.
    }
  }
case .failure(let placesError):
  // Handle error.
}
  

let token = GMSAutocompleteSessionToken()

let origin = CLLocation(latitude: 37.7749, longitude: -122.4194)

let filter = GMSAutocompleteFilter()

filter.origin =  origin

let request = GMSAutocompleteRequest(query:"Amoeba")
request.filter = filter
request.sessionToken = token

GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { ( results, error ) in
      if let error = error {
        print("Autocomplete error: \(error)")
        return
      }
      if let autocompleteResults = results {
        for result in autocompleteResults {
          print("Result \(String(describing: result.placeSuggestion?.placeID)) with \(String(describing: result.placeSuggestion?.attributedFullText)) and distance: \(String(describing: result.placeSuggestion?.distanceMeters))")
        }
      }
    })

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.origin = [[CLLocation alloc] initWithLatitude:37.395804 longitude:-122.077023];
GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Amoeba"];
request.sessionToken = token;
request.filter = filter;

[[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){
  // Handle response
  for (GMSAutocompleteSuggestion *suggestion in results) {
    if (suggestion.placeSuggestion) {
      // Show place suggestion data.
      }
    }
}];

Настройте контент и тему

let uiCustomization = AutocompleteUICustomization(
    listDensity: .multiLine,
    listItemIcon: .noIcon,
    theme: PlacesMaterialTheme()
)

Как добавить виджет автозаполнения мест (полный код)

struct PlaceAutocompleteDemoView: View {

  @State private var fetchedPlace: Place?
  @State private var placesError: PlacesError?
  @State private var showWidget = false

  public var body: some View {
    VStack {
      Button("Search for a place") {
        showWidget.toggle()
      }
      .placeAutocomplete(
        show: $showWidget,
        onSelection: { (autocompletePlaceSuggestion, autocompleteSessionToken) in
          Task {
            let placesClient = await PlacesClient.shared
            let fetchPlaceRequest = FetchPlaceRequest(
              placeID: autocompletePlaceSuggestion.placeID,
              placeProperties: [.displayName, .formattedAddress],
              sessionToken: autocompleteSessionToken
            )

            switch await placesClient.fetchPlace(with: fetchPlaceRequest) {
            case .success(let place):
              print("Fetched place: \(place)")
              self.fetchedPlace = place
            case .failure(let placesError):
              print("Failed to fetch place: \(placesError)")
              self.placesError = placesError
            }
          }
        },
        onError: { placesError in
          self.placesError = placesError
        }
      )
    }
  }
}

Оптимизация Autocomplete (New)

В этом разделе приведены рекомендации по эффективному использованию сервиса Autocomplete (New).

Рассмотрим некоторые общие рекомендации.

• Чтобы быстро разработать пользовательский интерфейс, используйте виджет Autocomplete (New) Maps JavaScript API, виджет Autocomplete (New) Places SDK для Android или виджет Autocomplete (New) Places SDK для iOS.
• В первую очередь ознакомьтесь с самыми важными полями данных Autocomplete (New).
• Поля с предпочтениями и ограничениями местоположений использовать не обязательно, но они могут значительно повлиять на производительность функции автозаполнения.
• Используйте обработку ошибок в приложении на случай, если API вернет ошибку.
• Убедитесь, что приложение сможет обработать тот случай, если пользователь не выберет место, и предложить вариант продолжения работы.

Рекомендации по оптимизации затрат

Базовая оптимизация затрат

Для оптимизации затрат на сервис Autocomplete (New) используйте маски полей в виджетах «Информация о местах» (New) и Autocomplete (New), чтобы они возвращали только нужные вам поля данных Autocomplete (New).

Дополнительная оптимизация затрат

Рассмотрите возможность программно реализовать сервис Autocomplete (New), чтобы получить доступ к тарифу SKU: Autocomplete Request и запрашивать результаты Geocoding API о выбранном месте вместо информации о местах (New). Тариф Per Request в сочетании Geocoding API будет выгоднее, чем тариф Per Session (на основе сеансов), если соблюдаются два следующих условия:

• Если вам нужны только широта и долгота или адрес выбранного пользователем места, получить эту информацию с помощью Geocoding API дешевле, чем вызывать Place Details (New).
• Если пользователи выбирают подсказку функции автозаполнения в среднем из первых четырех запросов подсказок Autocomplete (New) или из меньшего числа, тариф Per Request может быть выгоднее, чем Per Session.

Возможно, для вашего приложения Geocoding API будет более выгодным вариантом, чем информация о местах (New). Это зависит от того, насколько эффективно вы используете Autocomplete (New). Эффективность функции автозаполнения (новый вариант) в каждом приложении зависит от того, какие запросы вводят пользователи, где используется приложение и реализованы ли рекомендации по оптимизации производительности.

Чтобы найти среднее количество запросов для таблицы, проанализируйте, сколько символов в среднем вводит пользователь, прежде чем выбирать подсказку Autocomplete (New) в приложении.

Автозаполнение (Новое) на основе сеансов с информацией о местах (Новое)

Используйте сервис Autocomplete (New) на основе сеансов совместно с информацией о местах (New).
Поскольку вашему приложению требуется информация о местах (New), например название места, статус компании или часы работы, в вашей реализации Autocomplete (New) должен использоваться токен сеанса (программно или встроенный в виджеты JavaScript, Android или iOS) для каждого сеанса, а также соответствующие коды Places в зависимости от того, какие поля данных о месте вы запрашиваете.¹

Реализация виджета
Функция автоматического управления сеансами встроена в виджеты для JavaScript, Android и iOS. В нее входят как запросы Autocomplete (New), так и запрос информации о местах (New) для выбранной подсказки. Обязательно укажите параметр fields, чтобы запрашивались только нужные поля данных Autocomplete (New).

Программная реализация
Используйте токен сеанса с запросами Autocomplete (New). При запросе информации о местах (New) по выбранной подсказке укажите следующие параметры:

1. идентификатор места из ответа Autocomplete (New);
2. токен сеанса, использованный в запросе Autocomplete (New);
3. Параметр fields, указывающий нужные поля данных Autocomplete (New).

Оплата за запрос Autocomplete (New) с Geocoding API

Реализуйте Autocomplete (New) программно без токенов сеансов и вызывайте Geocoding API для выбранной подсказки места.
Geocoding API предоставляет адреса и координаты широты и долготы. Четыре запроса Autocomplete вместе с вызовом Geocoding API о выбранной подсказке места стоят меньше, чем один сеанс Autocomplete (New)¹.

Вы можете применить рекомендации по оптимизации эффективности, чтобы помочь пользователям получать нужные подсказки, вводя минимальное количество символов.

Autocomplete (New) на основе сеансов для приложений, работающих только с адресами

Используйте сервис Autocomplete (New) на основе сеансов совместно с информацией о местах (New).
Поскольку среднее количество запросов, которые вы ожидаете сделать до того, как пользователь выберет подсказку Autocomplete (New), превышает стоимость тарифа за сеанс, в вашей реализации Autocomplete (New) должен использоваться токен сеанса как для запросов Autocomplete (New), так и для связанного запроса информации о местах (New) за сеанс. ¹

Реализация виджета
Функция автоматического управления сеансами встроена в виджеты для JavaScript, Android и iOS. В нее входят как запросы Autocomplete (New), так и запрос информации о местах (New) для выбранной подсказки. Обязательно укажите параметр fields, чтобы запрашивались только нужные поля.

Программная реализация
Используйте токен сеанса с запросами Autocomplete (New). При запросе информации о местах (New) о выбранной подсказке включите следующие параметры:

1. идентификатор места из ответа Autocomplete (New);
2. токен сеанса, использованный в запросе Autocomplete (New);
3. Параметр fields, указывающий поля, например адрес и геометрические данные.

Рассмотрите возможность откладывать запросы Autocomplete (New)
Вы можете попробовать различные стратегии, например откладывать запрос Autocomplete (New), пока пользователь не введет первые три или четыре символа, чтобы ваше приложение совершало меньше запросов. Например, если вы отправляете запросы Autocomplete (New) для каждого символа после того, как пользователь ввел третий символ, то, если пользователь введет семь символов, а затем выберет подсказку, для которой вы отправите один запрос Geocoding API, общая стоимость будет равна стоимости четырех запросов Autocomplete (New) Per Request и одного запроса Geocoding API¹.

Если при откладывании запросов среднее число программных запросов станет меньше четырех, вы сможете эффективно использовать сервис Autocomplete (New) с Geocoding API. Обратите внимание, что пользователь, ожидающий появления подсказок с каждым введенным символом, может принять откладывание запросов за задержку.

Вы можете применить рекомендации по оптимизации эффективности, чтобы помочь пользователям получать нужные подсказки, вводя меньше символов.

Рекомендации по повышению эффективности

В рекомендациях ниже описаны способы оптимизации производительности Autocomplete (New):

• Добавьте в свою реализацию Autocomplete (New) ограничения для отдельных стран, смещение местоположения и (для автоматизированных реализаций) языковые настройки. Предпочитаемый язык не нужен в случае виджетов, потому что для них язык определяется на основе языковых настроек браузера или мобильного устройства.
• Если вместе с Autocomplete (New) отображается карта, вы можете сделать предпочитаемым местоположением видимую область карты.
• Если пользователь не выберет ни одну из подсказок Autocomplete (New) – чаще всего такое бывает, если ни одна из них не соответствует искомому адресу, — вы можете повторно использовать изначально введенные пользователем данные, чтобы получить более подходящие результаты:
  • Если вы рассчитываете, что пользователь будет вводить только информацию об адресе, повторно используйте изначально введенные им данные в вызове Geocoding API.
  • Если пользователь скорее всего будет вводить запросы для определенного места по названию или адресу, используйте запрос информации о местах (New). Если ожидается, что результаты будут из определенного региона, используйте предпочтение местоположений.
  К другим сценариям, при которых лучше вернуться к использованию Geocoding API, относятся следующие:
  • Пользователи вводят адреса, содержащие номер квартиры или офиса. Так, для адреса в Чехии "Stroupežnického 3191/17, Praha" Autocomplete (New) покажет частичную подсказку.
  • Пользователь вводит адрес с префиксом для ряда домов, например "23-30 29th St, Queens" в Нью-Йорке или "47-380 Kamehameha Hwy, Kaneohe" на острове Кауаи (Гавайи).

Привязка к местоположению

Настроить предпочтение результатов из определенной области с помощью параметров location и radius. Это указывает Autocomplete (New), что результаты в пределах заданной области должны показываться в первую очередь. однако более отдаленные точки также могут быть включены в ответ. С помощью параметра includedRegionCodes можно отфильтровать результаты, чтобы в них показывались только места в указанной стране.

Ограничение местоположений

Ограничить результаты определенной областью, передав параметр locationRestriction.

Вы также можете ограничить результаты регионом, заданным параметрами location и radius, добавив параметр locationRestriction. В этом случае Autocomplete (New) будет возвращать результаты только в пределах этого региона.