Suggest API | 2GIS Documentation

Suggest API

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

suggest

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

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

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

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

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

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

Подсказка адреса предлагает по введённой части адреса возможные варианты для ввода его остальной части. Для получения подсказки адреса в запрос нужно добавить параметр suggest_type=address. В подсказке отображаются улицы и номера домов. Чтобы в подсказке отображались только улицы, добавьте в запрос suggest_type=street.

Для получения подсказки по введённому фрагменту конечной точки маршрута добавьте в запрос параметр suggest_type=route_endpoint. В подсказке отображаются дома, компании, остановки и другие объекты справочника, привязанные к точке на карте. Они подбираются по частичному или полному совпадению текста в поле поиска.

В подсказке отображаются только объекты справочника — дома, компании, остановки и другие. Подсказки подбираются без привязки к точке на карте, например, интернет-магазины. В результаты не попадает дополнение текста пользовательского запроса. В запрос нужно добавить suggest_type=object.

Ответ на запрос возвращается в формате 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 — тип подсказки. Это может быть предполагаемый текст пользовательского запроса или список объектов из справочников. Полный список типов можно узнать в описании API.

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