Suggest API

Suggest API предназначен для формирования подсказок для поиска объектов. Для отображения поисковых подсказок пользователю достаточно начать вводить текст в поле поиска. Suggest API предложит возможные варианты объектов, подходящих под критерии поиска. Пользователю останется только выбрать из предложенных вариантов. Подсказки учитывают местоположение пользователя.

Запросы осуществляются методом GET, все необходимые параметры передаются в строке запроса. Ответы формируются в формате JSON.

Базовые настройки Suggest API оптимизированы для ускорения ввода запроса и совместного использования с Places API. Если запрос состоит из нескольких критериев, например, «кафе с Wi-Fi», то часть результатов будет популярными запросами или контейнерами.

Чтобы получить конечный объект справочника, передайте полученные запросы или контейнеры на вход Places API. Чтобы использовать Suggest API без Places API, укажите подходящий suggest_type как будет показано ниже.

Формат запроса

В данном разделе приведён пример запроса

https://catalog.api.2gis.com/3.0/suggests?q=каф&location=37.630866,55.752256&key=YOUR_KEY

В запросе используются следующие параметры:

q=каф — поиск выполняется по запросу «каф» и допускает разные варианты продолжения запроса. Например: «кафе», «кафетерий», «кафедральный собор», «кафель» и т. д.;
location=37.630866,55.752256 — координаты точки, в окрестности которой выполняется поиск;
key=YOUR_KEY — ваш ключ API.

Типы подсказок

Параметр запроса suggest_type отвечает за результат подбора подсказок. По умолчанию suggest_type=object и подсказки относятся к объектам справочника (категориям, компаниям, улицам, городам и т. д.).

Ниже описаны самые используемые типы подсказок. С полным списком типов подсказок можно ознакомиться в описании API.

Подсказка объектов справочника
Подсказка адреса
Подсказка конечной точки маршрута

Подсказка объектов справочника

В подсказке отображаются только объекты справочника — дома, компании, остановки и другие. В ответ попадают как текстовые подсказки, которые подбираются без привязки к точке на карте (например, «кафе с Wi-Fi»), так и конкретные объекты. В результаты также попадает и дополнение текста пользовательского запроса.

Чтобы получить подсказки по объектам справочника, добавьте в запрос параметр suggest_type=object.

Подсказка адреса

Подсказка адреса предлагает по введённой части адреса возможные варианты для ввода его остальной части.

Чтобы получить подсказки с названиями улиц и номерами домов, добавьте в запрос параметр suggest_type=address.

Чтобы получить подсказки только с названиями улиц, добавьте в запрос параметр suggest_type=street.

Подсказка конечной точки маршрута

В подсказке отображаются дома, компании, остановки и другие объекты справочника, привязанные к точке на карте. Они подбираются по частичному или полному совпадению текста в поле поиска.

Чтобы получить подсказки по введённому фрагменту конечной точки маршрута, добавьте в запрос параметр suggest_type=route_endpoint.

Формат ответа на запрос

Ответ на запрос возвращается в формате JSON:

{
    "meta": {
        "api_version": "3.0.428313",
        "code": 200,
        "issue_date": "20200513"
    },
    "result": {
        "items": [
            {
                "search_attributes": {
                    "handling_type": 2,
                    "suggest_parts": [
                        {
                            "is_suggested": false,
                            "text": "каф"
                        },
                        {
                            "is_suggested": true,
                            "text": "е с wifi"
                        }
                    ],
                    "suggested_text": "кафе с wifi"
                },
                "type": "user_query"
            }
        ],
        "total": 1
    }
}

Параметры ответа на запрос

Ответ на запрос содержит параметры:

suggested_text - текст для отображения подсказки. Для текстовых подсказок - это текст полного запроса, который достраивается Suggest API на основе текста запроса введенного пользователем. Для подсказок объектов из справочника - это один из текстов объекта, по которому Suggest API нашёл его. Например, для запроса «кремль» и результата "Московский кремль" в suggested_text будет "Кремль".
suggest_parts - составной объект поясняющий, какая часть текста была введена пользователем ("is_suggested": false), а какая часть была предложена Suggest API ("is_suggested": true).

Как начать работать с API

Получите ключ. Для этого заполните анкету.
Изучите формат запроса и формат ответа.
Изучите примеры запросов к Suggest API.