Геосаджест
Геосаджест - это встроенный функционал API Яндекс Карт для быстрого ввода и проверки названий организаций и адресов во время ввода поисковых запросов от пользователей. При помощи геосаджеста в MapKit SDK можно сформировать список поисковых подсказок (геосаджестов) и сделать процесс ввода поискового запроса более простым и удобным.
Важно
Функционал геосаджеста доступен в full-версии MapKit SDK.
Выполнение запроса геосаджестов
Принцип выполнения запроса геосаджестов похож на создание поискового запроса, но имеет несколько важных отличий. Для создания запроса нужно выполнить следующие шаги:
-
Создайте новый экземпляр класса SearchManager или используйте существующий.
final searchManager = SearchFactory.instance.createSearchManager(SearchManagerType.Combined);
-
При помощи метода SearchManager.createSuggestSession создайте экземпляр сессии геосаджеста.
final suggestSession = searchManager.createSuggestSession();
-
Создайте экземпляр класса SuggestOptions, чтобы задать параметры запроса геосаджестов.
Пример параметров для поиска только по организациям.
final suggestOptions = SuggestOptions(suggestTypes: SuggestType.Biz.value);
-
С помощью метода SearchSuggestSession.suggest создайте новый запрос геосаджестов.
Данный пример начнет поиск возможных поисковых запросов, которые имеют префикс
"ho"
, например:"Hotels"
,"Hospitals"
и т.п.suggestSession.suggest( BoundingBox(map.visibleRegion.bottomLeft, map.visibleRegion.topRight), suggestOptions, suggestListener, text: "ho", );
-
Во время создания запроса геосаджестов, используйте следующий механизм для получения результатов геосаджеста.
final class SuggestListenerImpl implements SearchSuggestSessionSuggestListener { @override void onResponse(SuggestResponse suggest) { // Handle geo suggest response } @override void onError(Error error) { // Handle geo suggest error } }
Реализация данного интерфейса передается в качестве аргумента во все методы создания запроса геосаджестов.
Сессия геосаджеста
Сессия геосаджеста представляет собой класс SearchSuggestSession, при помощи которого осуществляется управление запросами.
Данный класс предоставляет следующий функционал:
-
SearchSuggestSession.suggest - используется для создания нового запроса геосаджестов. Принимает следующие аргументы:
text
- текст, по которому будут строиться поисковые подсказки;window
- текущее положение окна карты;- параметры геосаджеста и объект
SuggestListener
.
-
SearchSuggestSession.reset - сбрасывает текущий запрос и внутреннее состояние сессии геосаджеста.
Важно
Как и для сессии поиска, приложение должно хранить ссылку на объект сессии геосаджеста. Иначе запрос будет отменен.
Параметры геосаджеста
При помощи параметров геосаджеста SuggestOptions можно задать:
-
suggestTypes
- тип поисковых объектов для подбора: организации, топонимы и общественный транспорт. Данный параметр является битовой маской, поэтому можно выбрать некоторое подмножество типов. -
userPosition
- текущая позиция пользователя. Используется для вычисления расстояния от позиции пользователя до объектов, которые могут быть предложены геосаджестом.
Результаты геосаджеста
Для получения результатов запроса геосаджестов используется подписка на интерфейс SearchSuggestSessionSuggestListener. Его реализация передается во время вызова метода создания запроса геосаджестов SearchSuggestSession.suggest.
Данный интерфейс содержит следующие callback-методы:
-
SearchSuggestSessionSuggestListener.onResponse - вызывается при успешном завершении запроса. Предоставляет список найденных подсказок, который состоит из объектов SuggestItem - саджестов.
-
SearchSuggestSessionSuggestListener.onError - вызывается при завершении запроса с ошибкой.
Данные саджестов
Класс SuggestItem предоставляет большое количество данных, ключевые из них:
type
- тип саджеста: топоним, организация или общественный транспорт.searchText
- текст, по которому нужно осуществить поиск если данный саджест был выбран.displayText
- текст для отображения в поле для ввода запроса.uri
- URI объекта.distance
- дистанция до объекта.action
- тип действия, которое должно быть осуществлено при выборе данного варианта: подстановка или мгновенный поиск.distance
- дистанция до объекта поиска.center
- положение на карте.
Отображение саджестов
Класс SuggestItem предоставляет информацию для удобного отображения саджестов на экране:
title
- короткое название саджеста.subtitle
- данные о местоположении, адрес.
Данные параметры имеют тип SpannableString. Он представляет собой строку, в которой выделены подстроки, совпадающие с текстом поискового запроса, введенного пользователем. Данные подстроки следует отрисовывать акцентными цветами.
Обработка нажатий на саджесты
При помощи SuggestItem.action можно получить тип действия, которое должно быть совершено при выборе данного саджеста:
-
Search - нужно выполнить новый поисковый запрос. Если SuggestItem.uri возвращает ненулевой URI, то нужно использовать поиск по URI. Если его нет, то нужно искать по тексту из метода SuggestItem.searchText. Используется, как правило, когда пользователь нажимает на название категории, например: "Кафе", "Ресторан", или на название организации.
-
Substitute - заменить текст текущего поискового запроса на SuggestItem.displayText и выполнить новый запрос геосаджеста. Обычно используется при поиске адресов: сначала подставляется название города, затем улица и т.д.