Обзор

Places API позволяет искать различные объекты: организации, здания, достопримечательности, остановки транспорта, парковки и многое другое.

Основные возможности

Вы можете искать объекты по:

названию организации («ИП Иванов»);
категории или сфере деятельности («рестораны» или «магазины музыкальных инструментов»);
атрибутам услуг и товаров («кафе с итальянской кухней» или «русская баня на дровах с бассейном»);
адресу («улица Бауманская, 32»);
географическому критерию в текстовом запросе («цветы у Бауманской») или в радиусе точки, районе, здании, городе и т. д.;
координатам («37.630866,55.752256»);
типу объекта (парковки, остановки, здания, улицы и другие);
идентификатору объекта («70000001029535674»);
сайту («2gis.ru»);
номеру телефона («667-02-99»);
ИНН («5405276278»);
торговой лицензии;
коду ФИАС;
бренду, времени работы, дате открытия и другим параметрам.

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

Расширенные возможности

Изучите также возможности других API поиска и дополните ваши сценарии работы с объектами на карте. Например, чтобы формировать подсказки при поиске объектов, используйте Suggest 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 и отправить запрос на поиск кафе рядом с точкой на карте.

Получение ключа доступа

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

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

Подробнее о работе с ключами и подписками см. в документации личного кабинета.

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

Запрос к Places API должен содержать:

Объект, который нужно найти. Вы можете искать здания, организации, остановки транспорта, парковки, достопримечательности и другие объекты. Подробнее см. в инструкциях Поиск объектов и Фильтрация по атрибутам.
Геоограничение поиска: где нужно искать объект. Подробнее см. в инструкции Геоограничение поиска.
Ваш API-ключ.

Также вы можете получать дополнительную информацию об объектах, обрабатывать результаты поиска, настраивать алгоритм поиска и т. д.

Чтобы найти кафе рядом с точкой на карте, отправьте GET-запрос к /3.0/items:

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

В запросе укажите:

q=кафе — текстовый запрос для поиска объекта: «кафе».
location=37.630866,55.752256 — геоограничение: координаты точки, рядом с которой выполняется поиск.
key=API_KEY — значение API-ключа.

Пример ответа

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

Краткий пример ответа:

{
    "meta": {
        "api_version": "3.0.20949",
        "code": 200,
        "issue_date": "20260703"
    },
    "result": {
        "items": [
            {
                "address_name": "улица Варварка, 6 ст3",
                "id": "70000001029535674",
                "name": "Зарядье, гастрономический центр",
                "type": "branch"
            },
            ...
        ],
        "total": 1289
    }
}

Где:

result.items — массив объектов, соответствующих запросу. Каждый объект содержит:
- address_name — адрес объекта.
- id — ID объекта.
- name — название объекта.
- type — тип объекта.
result.total — общее количество объектов, соответствующих запросу.

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

Подробнее о каждом параметре см. в Справочнике API.

Тарифы и лимиты

Стоимость сервиса рассчитывается исходя из количества успешных запросов в месяц. Успешным запросом к API считается запрос, который возвращает HTTP-код 200 в поле meta.code в теле ответа, например:
```
{
    "meta": {
        "api_version": "3.0.17799",
        "code": 200,
        "issue_date": "20240524"
    },
    ...
}
```
Для демо-ключей и ключей, созданных в рамках подписки, действуют лимиты на использование сервиса.
Актуальную стоимость и лимиты см. в инструкции Тарифы.

Варианты размещения

Облако: все актуальные методы Places API доступны через публичные endpoint-ы 2ГИС.
On-Premise: все актуальные методы Places API доступны при установке API-платформы 2ГИС в закрытом контуре. Подробнее см. в разделе API-платформа для сервера.

Методы, отмеченные как deprecated, устарели и не поддерживаются в обоих вариантах размещения.

Помощь

Если у вас возникли вопросы при работе с API, задайте их AI-ассистенту (в правом нижнем углу сайта), воспользуйтесь поиском по документации или отправьте электронное письмо на api@2gis.ru.
Если вы хотите обсудить возможности API или его интеграцию с вашим продуктом, обратитесь к менеджеру.

Что дальше?

Примеры работы Places API.
Справочник API.

Основные возможности​

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

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

Получение ключа доступа​

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

Пример ответа​

Тарифы и лимиты​

Варианты размещения​

Помощь​

Что дальше?​