Places API

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

Вы можете найти одно или несколько мест по различным критериям:

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

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

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

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

1. Получите ключ доступа:

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

   Важно

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

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

2. Изучите формат запроса и ответа.

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

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

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

• Методы API:

  • /3.0/items/bysite — поиск компаний по сайту;
  • /3.0/items/byphone — поиск компаний по номеру телефона;
  • /3.0/items/byitin — поиск компаний по ИНН;
  • /3.0/items/bytradelicense — поиск компаний по торговой лицензии;
  • /3.0/items/byfias — поиск компаний по ФИАС-коду.

• Поля (указываются с помощью параметра 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 — категория объекта культурного наследия.

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

Любой запрос к Places API должен содержать следующие компоненты:

1. Запрос для поиска объекта (что нужно искать?). Этот компонент обязателен всегда. Вы можете оформить запрос разными способами:

   • В виде текстового запроса (параметр q) с разной степенью уточнения:

     • с названием конкретного места (кафе «Шоколадница»);
     • с интересующей вас категорией (магазины музыкальных инструментов);
     • с интересующим вас критерием (рестораны с итальянской кухней) и т.д.

   • В виде фильтра по желаемому атрибуту (например, по времени работы). Подробнее об этом см. ниже.

   • С указанием ID конкретного объекта или категории.

   • С указанием известного атрибута конкретного объекта: номера телефона, адреса веб-сайта, ИНН или торговой лицензии.

2. Геоограничение поиска (где нужно искать?). Этот параметр обязателен при поиске списка объектов по определённым критериям (например, поиск всех круглосуточных магазинов цветов в Москве). Вы можете задать ограничение разными способами:

   • В текстовом запросе (параметр q). Вы можете указать желаемый регион, город, район, улицу, станцию метро и т.д.

     Вы можете объединить запрос для поиска объекта и геоограничение в одной формулировке (кафе в Тверском районе Москвы). Параметр q должен быть только один.

   • С указанием ID желаемого города, здания, станции метро и т.д.

   • С определением области поиска:

     • в радиусе вокруг точки;
     • в прямоугольной области;
     • в произвольной области.

   Примечание

   Геоограничение можно не задавать, если вы ищете конкретный объект по его уникальному свойству с помощью следующих методов:

   • /3.0/items/byid,
   • /3.0/items/bysite,
   • /3.0/items/byphone,
   • /3.0/items/byservicing,
   • /3.0/items/byitin,
   • /3.0/items/bytradelicense,
   • /3.0/items/byfias.

3. Ваш ключ API.

Также вы можете применить дополнительные настройки поиска.

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

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

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

• q=кафе — поиск выполняется по текстовому запросу «кафе»;
• location=37.630866,55.752256 — геоограничение: координаты точки, в окрестности которой выполняется поиск кафе;
• key=YOUR_KEY — ваш ключ 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 отвечает за тип поиска: алгоритм и настройки, оптимизированные под определенную цель и логику формирования результатов поиска.

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

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

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

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

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

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

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

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

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

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