Places API

Places API выполняет поиск организаций, зданий и мест.

Поиск может осуществляться:

по названию компании («ИП Голубёв»);
по сфере деятельности («рестораны» или «магазины музыкальных инструментов»);
с геокритерием («цветы у Бауманской»);
с атрибутами услуг и товаров («кафе с итальянской кухней» или «русская баня на дровах с бассейном»);
по телефону и сайту («667-02-99» или «grabli.ru»);
по ИНН («5405276278»);
по торговой лицензии;
без указания текстового запроса (в здании, в категории, в городе, поиск всех филиалов одной компании).

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

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

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

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

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

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

Фильтрация результата поиска по типу объекта

Параметр type используется в запросе для фильтрации объектов по типу. Поиск будет выполняться только среди объектов указанного в запросе типа. Наиболее используемый список признаков, по которым возможна фильтрация:

по местоположению — например, в определённом районе, городе, в заданной области;
по типу данных в ответе — например, когда нужны только компании или только здания;
по категории — например, только кафе или только продуктовые магазины;
по организации — можно получить список всех филиалов одной организации;
по времени работы — например, только круглосуточно работающие филиалы;
по наличию или отсутствию данных — например, фотографий, отзывов, рейтинга, сайта, ИНН;
по дополнительным атрибутам — например, наличию Wi-Fi, возможности оплаты картой и т.д.

Полный список фильтров и соответствующие им параметры можно изучить на странице описания API.

Фильтрация результата поиска по дополнительным атрибутам

Список доступных дополнительных атрибутов (ДА) для фильтрации является динамическим. Его можно увидеть указав в параметре fields значение filters. В ответе ДА будут перечислены в поле result.filters.attributes.

Чтобы отфильтровать результаты по одному или нескольким ДА, каждый из них нужно передать в виде отдельного параметра attr[<code>]=<value>, где <code> - код дополнительного атрибута, <value> - значение дополнительного атрибута. Для ДА с типом flag - это булево значение, для ДА с типом range - диапазон из двух целых чисел, перечисленных через запятую. Такой способ фильтрации результата актуален только для ДА с типами flag и range.

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

Дополнительная информация об объекте

Параметр fields используется для получения дополнительной информации об объекте.

Сортировка результата поиска

Подключить сортировку результата поиска можно с помощью параметра sort в запросе.

Результат поиска сортируется по удалённости от местоположения пользователя, рейтингу объекта и другим параметрам. Виды сортировки определены в описании API.

Поиск в области на карте

Объекты можно искать в области на карте. Данный вид поиска позволяет получить релевантные результаты. Варианты поиска в области на карте:

геокритерий в текстовом запросе — запрос «Москва кафе»;
точка, относительно которой выполняется поиск;
поиск в радиусе;
поиск в прямоугольной области;
поиск в произвольной области;
поиск в городе.

Для поиска объектов в области на карте в запросе передаются координаты точек, в границах которых будут найдены объекты, или идентификатор города, в котором будет выполняться поиск объектов. С подробным описанием полей можно ознакомиться на странице описания API, c примерами использования геоограчений — на соответствующей странице.

Поиск информации об организации

Организацию можно найти по ИНН, номеру телефона, адресу сайта и торговой лицензии. Такой поиск не учитывает местоположение пользователя. Результатом поиска является список организаций. Полное описание всех методов и параметров для поиска можно изучить на странице описания API.

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

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

{
    "meta": {
        "api_version": "3.0.448950",
        "code": 200,
        "issue_date": "20200626"
    },
    "result": {
        "items": [
            {
                "address_comment": "3, 5 этаж",
                "address_name": "Никольская, 25",
                "id": "70000001031668425",
                "name": "МСК, сеть лаундж-баров",
                "type": "branch"
            }
        ],
        "total": 5926
    }
}

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

В ответе на запрос по умолчанию передаются параметры:

id — идентификатор объекта;
name — название объекта;
type — тип объекта. Типы объектов определены в описании API.

Дополнительную информацию об объекте можно передать в параметре fields. Возможно получение дополнительной информации:

точка, к которой привязан объект;
адрес или местоположение объекта и его привязка к административно-территориальным единицам;
информация о геометрии объекта, визуальный центр геометрии;
информация о родительской организации, к которой относятся все филиалы компании;
расписание работы;
контактная информация;
связанные с компанией или местом объекты — точки входа, ближайшие остановки и парковки, обслуживающие организации, подъезды в здании и другие;
подробная информация о парковках — вместимость, стоимость, тип доступа, количество уровней;
подробная информация о здании — этажность, материал здания.

Перечень дополнительной информации определён в описании API.

Формирование результата поиска

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

Поиск с раскрытием

Поиск, при котором категории и организации будут раскрыты до компаний (филиалов организации). Например, при поиске «почта России» в ответе будут все почтовые отделения. Аналогично работает раскрытие категории — при поиске «кафе» в результате будут компании в категории «Кафе / Кондитерские», а не сама категория, которая также является объектом справочника. Этот алгоритм формирования результата используется по умолчанию и соответствует переданному в запрос параметру search_type=discovery.

Поиск с единственным филиалом одной организации в результате

Аналогичен поиску с раскрытием, но для каждой организации в результат выводится только один филиал. Например, пользователь хочет найти интернет-магазин и посмотреть его сайт, и ему не нужны все пункты выдачи, которые будут в результате. Для изменения алгоритма формирования результата нужно передать в запрос search_type=one_branch.

Поиск в здании

Подходит для поиска организаций в здании, например, в бизнес-центре или торгово-развлекательном центре. Также можно использовать для автодополнения при поиске в здании. Для изменения алгоритма формирования результата нужно передать в запрос search_type=indoor и указать id здания в параметре building_id.

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

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