Suggest API

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

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

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

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

Изучите также возможности других API поиска и дополните ваши сценарии работы с объектами на карте.

Начало работы

Получите ключ доступа:
1. Зарегистрируйтесь в личном кабинете Менеджер Платформы.
2. Создайте демо-ключ или купите ключ для доступа к API: см. инструкцию Ключи доступа.
Важно

Для получения некоторой информации об объектах требуется дополнительное согласование. Изучите список методов и полей для получения дополнительной информации по запросу.

Работать с ключами можно в Менеджере Платформы: подробнее см. в документации личного кабинета.
Изучите формат запроса и формат ответа.
Изучите примеры запросов к Suggest API.

Дополнительная информация по запросу

Получение некоторой информации об объектах доступно только по запросу и за дополнительную плату. Cвяжитесь с отделом продаж 2ГИС, чтобы приобрести доступ к полям ниже.

Поля указываются с помощью параметра fields:

items.contact_groups — контакты компании;
items.floors — количество этажей;
items.floor_plans — планы этажей;
items.links.database_entrances.apartments_info — информация о квартирах в доме;
items.employees_org_count — численность сотрудников организации;
items.itin — индивидуальный номер налогоплательщика;
items.trade_license — лицензия филиала;
items.fias_code — код ФИАС улиц и административных территорий;
items.address.components.fias_code — код ФИАС зданий;
items.fns_code — код ФНС административных территорий;
items.okato — код ОКАТО улиц и административных территорий;
items.address.components.okato — код ОКАТО зданий;
items.oktmo — код ОКТМО улиц и административных территорий;
items.address.components.oktmo — код ОКТМО зданий;
items.structure_info.material — данные о материале здания;
items.structure_info.apartments_count — данные о количестве квартир;
items.structure_info.porch_count — данные о количестве подъездов;
items.structure_info.floor_type — тип перекрытий в здании;
items.structure_info.gas_type — тип газоснабжения здания;
items.structure_info.year_of_construction — год постройки здания;
items.structure_info.elevators_count — количество лифтов в здании;
items.structure_info.is_in_emergency_state — факт признания дома аварийным;
items.structure_info.project_type — серия или проект постройки здания;
items.structure_info.chs_name — название объекта культурного наследия;
items.structure_info.chs_category — категория объекта культурного наследия.

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

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

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).