Обзор | 2GIS Documentation
Suggest API

Suggest API

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

suggest

Запросы осуществляются методом 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).
  1. Получите ключ:

    1. Зарегистрируйтесь в личном кабинете Platform Manager.
    2. Создайте демо-ключ (если вы еще не пользовались продуктами 2ГИС) или запросите боевой ключ по ссылке для связи с менеджером на вкладке Ключи API.

    В личном кабинете вы также можете:

    • Просматривать информацию по своим уже созданным ключам: какие сервисы подключены, какой лимит задан по каждому из них, когда ключ будет деактивирован.
    • Задавать ограничения на ключ по HTTP-заголовкам или по IP и подсетям.
    • Изучать статистику распределения запросов по каждому ключу.
  2. Изучите формат запроса и формат ответа.

  3. Изучите примеры запросов к Suggest API.