Places API

API предоставляет подробную информацию о местах.

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

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

Пример запроса и ответа

В примере выполняется поиск по запросу «кафе» и задаётся точка, относительно которой осуществляется поиск.

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

Не забудьте заменить YOUR_KEY на ваш ключ API (см. Как начать работать с 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
    }
}

Какие данные можно получить в ответе

В результате запроса можно получить места, такие как компании, здания, остановки, улицы и другие. Фильтровать типы данных можно с помощью параметра type в запросе.

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

Возможно отображение таких данных, как:

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

С полным списком дополнительных полей можно ознакомиться в описании API.

Изменение логики поиска

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

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

Поиск, при котором категории и организации будут раскрыты до компаний (филиалов организации). Например, при поиске "почта россии" в ответе будут все почтовые отделения. Аналогично работает раскрытие категории - при поиске "кафе" в результате будут компании в категории "Кафе / Кондитерские", а не сама категория, которая так же является объектом справочника.

Эта логика используется по умолчанию и соответствует переданному в запрос параметру search_type=discovery.

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

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

Для изменения логики поиска нужно передать в запрос search_type=one_branch.

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

Подходит для поиска в здании с большим количеством компаний, например, в бизнес-центре или торгово-развлекательном центре. Также можно использовать для автодополнения при поиске в здании.

Для переключения логики поиска нужно передать в запрос search_type=indoor и указать id здания в параметре building_id.

Фильтрация результатов

В зависимости от решаемой задачи можно изменять результат поиска, передавая в запрос дополнительные фильтры.

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

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

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

Поиск с геоограничениями

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

Варианты указания зоны поиска:

геокритерий в текстовом запросе - запрос "Москва кафе";
точка, относительно которой осуществляется поиск - параметр sort_point;
поиск в радиусе - параметры point или lon,lat и radius;
поиск в прямоугольной области - параметры point1 и point2;
поиск в произвольной области - параметр polygon;
поиск в городе - параметр city_id.

С подробным описанием полей можно ознакомиться в разделе "Описание API", с примерами использования геоограчений - в разделе "Примеры".

При отсутствии геоограничений релеватные результаты можно получить только при поиске компаний по данным.

Поиск компаний по данным

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

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

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