Геосаджест

Геосаджест - это встроенный функционал API Яндекс Карт для быстрого ввода и проверки названий организаций и адресов во время ввода поисковых запросов от пользователей. При помощи геосаджеста в MapKit SDK можно сформировать список поисковых подсказок (геосаджестов) и сделать процесс ввода поискового запроса более простым и удобным.

Выполнение запроса геосаджестовВыполнение запроса геосаджестов

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

1. Создайте новый экземпляр класса YMKSearchManager или используйте существующий.

   let searchManager = YMKSearch.sharedInstance().createSearchManager(with: .combined)
   

2. При помощи метода YMKSearchManager.createSuggestSession() создайте экземпляр сессии геосаджеста.

   let suggestSession = searchManager.createSuggestSession()
   

3. Создайте экземпляр класса YMKSuggestOptions, чтобы задать параметры запроса геосаджестов.

   Пример параметров для поиска только по организациям.

   let suggestOptions = {
       let options = YMKSuggestOptions()
       options.suggestTypes: .biz
   }()
   

4. С помощью метода YMKSearchSuggestSession.suggest(withText:window:suggestOptions:responseHandler:) создайте новый запрос геосаджестов.

   Данный пример начнет поиск возможных поисковых запросов, которые имеют префикс "ho", например: "Hotels", "Hospitals" и т.п.

   suggestSession.suggest(
       withText: "ho",
       window: YMKBoundingBox(
           southWest: map.visibleRegion.bottomLeft,
           northEast: map.visibleRegion.topRight
       ),
       suggestOptions: suggestOptions,
       responseHandler: handleSuggestSessionResponse
   )
   

5. Во время создания запроса геосаджестов, используйте следующий механизм для получения результатов геосаджеста.

   func handleSuggestSessionResponse(response: YMKSuggestResponse?, error: Error?) {
       if let error {
           // Handle geo suggest error
           return
       }
   
       // Handle geo suggest response
   }
   

   Данная функция-обработчик передается в качестве аргумента во все методы создания запроса геосаджестов.

Сессия геосаджестаСессия геосаджеста

Сессия геосаджеста представляет собой класс YMKSearchSuggestSession, при помощи которого осуществляется управление запросами.

Данный класс предоставляет следующий функционал:

• YMKSearchSuggestSession.suggest(withText:window:suggestOptions:responseHandler:) - используется для создания нового запроса геосаджестов. Принимает следующие аргументы:

  • text - текст, по которому будут строиться поисковые подсказки;
  • window - текущее положение окна карты;
  • параметры геосаджеста и объект SuggestListener.

• YMKSearchSuggestSession.reset() - сбрасывает текущий запрос и внутреннее состояние сессии геосаджеста.

Параметры геосаджестаПараметры геосаджеста

При помощи параметров геосаджеста YMKSuggestOptions можно задать:

• suggestTypes - тип поисковых объектов для подбора: организации, топонимы и общественный транспорт. Данный параметр является битовой маской, поэтому можно выбрать некоторое подмножество типов.

• userPosition - текущая позиция пользователя. Используется для вычисления расстояния от позиции пользователя до объектов, которые могут быть предложены геосаджестом.

Результаты геосаджестаРезультаты геосаджеста

Для получения результатов запроса геосаджестов используется обработчик YMKSearchSuggestSessionResponseHandler. Он принимается в качестве аргумента при вызове метода создания запроса геосаджестов YMKSearchSuggestSession.suggest(withText:window:suggestOptions:responseHandler:).

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

1. response - оповещает об успешном завершении запроса геосаджестов, если содержит не nil значение. Предоставляет объект YMKSuggestResponse, который содержит информацию о результатах запроса.

2. error - оповещает о завершении запроса геосаджестов с ошибкой, если не nil.

Данные саджестовДанные саджестов

Класс YMKSuggestItem предоставляет большое количество данных, ключевые из них:

• type - тип саджеста: топоним, организация или общественный транспорт.
• searchText - текст, по которому нужно осуществить поиск если данный саджест был выбран.
• displayText - текст для отображения в поле для ввода запроса.
• uri - URI объекта.
• distance - дистанция до объекта.
• action - тип действия, которое должно быть осуществлено при выборе данного варианта: подстановка или мгновенный поиск.
• distance - дистанция до объекта поиска.
• center - положение на карте.

Отображение саджестовОтображение саджестов

Класс YMKSuggestItem предоставляет информацию для удобного отображения саджестов на экране:

• title - короткое название саджеста.
• subtitle - данные о местоположении, адрес.

Данные параметры имеют тип YMKSpannableString. Он представляет собой строку, в которой выделены подстроки, совпадающие с текстом поискового запроса, введенного пользователем. Данные подстроки следует отрисовывать акцентными цветами.

Обработка нажатий на саджестыОбработка нажатий на саджесты

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

• search - нужно выполнить новый поисковый запрос. Если YMKSuggestItem.uri возвращает ненулевой URI, то нужно использовать поиск по URI. Если его нет, то нужно искать по тексту из метода YMKSuggestItem.searchText. Используется, как правило, когда пользователь нажимает на название категории, например: "Кафе", "Ресторан", или на название организации.

• substitute - заменить текст текущего поискового запроса на YMKSuggestItem.displayText и выполнить новый запрос геосаджеста. Обычно используется при поиске адресов: сначала подставляется название города, затем улица и т.д.

Исходный кодИсходный код

С примером использования геосаджеста в MapKit SDK можно ознакомиться в приложении MapSearch в нашем репозитории на GitHub.