Геосаджест

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

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

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

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

   val searchManager = SearchFactory.getInstance().createSearchManager(SearchManagerType.COMBINED)
   

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

   val suggestSession = searchManager.createSuggestSession()
   

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

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

   val suggestOptions = SuggestOptions()
       .setSuggestTypes(
           SuggestType.BIZ.value
       )
   

4. С помощью метода SuggestSession.suggest создайте новый запрос геосаджестов.

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

   suggestSession.suggest(
       "ho",
       BoundingBox(map.visibleRegion.bottomLeft, map.visibleRegion.topRight),
       suggestOptions,
       suggestListener,
   )
   

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

   val suggestListener = object : SuggestSession.SuggestListener {
       override fun onResponse(items: MutableList<SuggestItem>) {
           // Handle geo suggest response.
       }
   
       override fun onError(error: Error) {
           // Handle geo suggest error.
       }
   }
   

   Реализация данного интерфейса передается в качестве аргумента во все методы создания запроса геосаджестов.

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

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

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

• SuggestSession.suggest - используется для создания нового запроса геосаджестов. Принимает следующие аргументы:

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

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

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

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

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

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

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

Для получения результатов запроса геосаджестов используется подписка на интерфейс SuggestListener. Его реализация передается во время вызова метода создания запроса геосаджестов SuggestSession.suggest.

Данный интерфейс содержит следующие callback-методы:

1. SuggestListener.onResponse - вызывается при успешном завершении запроса. Предоставляет список найденных подсказок, который состоит из объектов SuggestItem - саджестов.

2. SuggestListener.onError - вызывается при завершении запроса с ошибкой.

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

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

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

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

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

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

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

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

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

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

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

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

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