Suggest API

API Suggest предназначен для формирования подсказок для поиска объектов. Для отображения поисковых подсказок пользователю достаточно начать вводить текст в поле поиска. API 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.

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

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