Обзор | 2GIS Documentation
Places API

Places API

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

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

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

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


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

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.

Для всех запросов обязательно указывать ограничение географии поиска. Доступны следующие варианты:

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

См. также:

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

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

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

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

Список доступных дополнительных атрибутов является динамическим. Чтобы увидеть его, укажите в запросе параметр &fields=filters. В ответе дополнительные атрибуты будут перечислены в поле result.filters.attributes.

Чтобы отфильтровать результаты по дополнительным атрибутам, передайте каждый из них в виде отдельного параметра attr[<code>]=<value>.

Здесь:

  • <code> — код дополнительного атрибута.

  • <value> — значение дополнительного атрибута. Тип значения зависит от типа атрибута:

    Тип атрибута Тип значения Пример
    flag Булево значение attr[food_service_business_lunch]=true
    range Диапазон из двух целых чисел, перечисленных через запятую attr[food_service_capacity]=10,30

Фильтрация по атрибутам с типом filter:

Тег атрибута Назначение Тип значения Пример
has_site Фильтр по наличию сайта Булево значение has_site=true
has_photos Фильтр по наличию фотографий Булево значение has_photos=true
bound Фильтр по прямоугольной области Строка (см. формат полей point1 и point2 в описании API) point1=82.921663,55.030195&point2=82.921663,55.030195

Фильтрация по остальным атрибутам:

Тег атрибута Назначение Тип значения Пример
district Фильтр по району Целое число (идентификатор района) district_id=141347373711435
worktime Фильтр по времени работы Строка (см. формат для параметра worktime в описании API) worktime=now
subway Фильтр по станции метро Целое число (идентификатор станции метро) subway=141523467371731

Если вы укажите несколько дополнительных атрибутов, в ответ попадут только те объекты, которые удовлетворяют всем условиям.

Атрибуты с типом sort в выдаче блока filters используются для сортировки результатов поиска

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

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

Результат поиска сортируется по удалённости от местоположения пользователя, рейтингу объекта и другим параметрам. Виды сортировки определены в описании 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
    }
}

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

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

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

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

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

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

Ниже описаны самые используемые типы поиска. Полный список см. в описании API.

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

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

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

  1. Получите ключ:

    1. Зарегистрируйтесь в личном кабинете Platform Manager.
    2. Создайте демо-ключ (если вы еще не пользовались продуктами 2ГИС) или запросите боевой ключ по ссылке для связи с менеджером на вкладке Ключи API.

    В личном кабинете вы также можете:

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

  3. Изучите примеры запросов к Places API.