Markers API

Markers API выполняет поиск организаций, зданий и мест для отображения маркеров на карте. Маркер является представлением объекта на карте, поэтому маркером может быть только объект с координатами.

Вы можете найти одно или несколько мест:

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

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

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

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

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

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

Запрос к Markers API должен содержать следующие компоненты:

Запрос для поиска объекта (что нужно искать?). Этот компонент обязателен всегда. Вы можете оформить запрос:
- В виде текстового запроса (параметр q) с разной степенью уточнения:
  - с названием конкретного места (кафе «Шоколадница»);
  - с интересующей вас категорией (магазины музыкальных инструментов);
  - с интересующим вас критерием (рестораны с итальянской кухней) и т. д.
- В виде фильтра по желаемому атрибуту (например, по времени работы). Подробнее об атрибутах см. ниже.
Геоограничение поиска (где нужно искать?). Этот параметр обязателен при поиске списка объектов по определённым критериям (например, поиск всех круглосуточных магазинов цветов в Москве). Вы можете задать ограничение:
- В текстовом запросе (параметр q): например, указать регион, город, район, улицу, станцию метро и т. д.
  
  Вы можете объединить запрос для поиска объекта и геоограничение в одной формулировке (кафе в Тверском районе Москвы). Параметр q должен быть только один.
- С указанием ID города, здания, станции метро и т. д.
- С определением области поиска:
Ваш ключ API.

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

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

https://catalog.api.2gis.com/3.0/markers?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": [
            {
                "id": "70000001041443567",
                "type": "branch",
                "lat": 55.433435,
                "lon": 37.728608,
                "is_advertising": false
            }
        ],
        "total": 5926
    }
}

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

id — идентификатор объекта.
type — тип объекта. Полный список типов см. в справочнике API.
lat — широта.
lon — долгота.
is_advertising — флаг, указывающий на рекламодателя.

Дополнительные настройки

Вы можете дополнительно настроить поиск, чтобы получить данные в нужном виде, например:

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

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

Чтобы получить дополнительную информацию в ответе, используйте параметр fields. Например, вы можете получить следующие данные об объекте:

рубрики, к которым относится объект;
идентификатор этажа, на котором расположен объект;
название объекта;
лицензию филиала.

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

Тип поиска

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

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

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

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

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

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

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

Чтобы изменить алгоритм формирования результатов поиска, передайте параметр search_type=one_branch в запросе.

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

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

Чтобы изменить алгоритм формирования результатов поиска, передайте параметр search_type=indoor в запросе и укажите ID здания в поле building_id.

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

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

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

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

Вы можете фильтровать результаты поиска:

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

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

Пример фильтрации по атрибутам:

Тег атрибута	Назначение	Тип значения	Пример
`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`	Фильтр по району, можно использовать только при поиске организаций (`type=branch`)	Целое число (идентификатор района)	`district_id=141347373711435`
`worktime`	Фильтр по времени работы	Строка (см. формат для параметра `work_time` в справочнике API)	`work_time=now`
`subway`	Фильтр по станции метро	Целое число (идентификатор станции метро)	`subway=141523467371731`

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

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

Тарифы

Стоимость сервиса рассчитывается исходя из количества запросов в месяц.
Актуальные тарифы можно посмотреть в Менеджере Платформы, в блоке Базовые сервисы.

Важно

1 декабря 2025 года обновлена сетка тарифов на API-сервисы. Подробнее об изменениях см. в личном кабинете.

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

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

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

Формат ответа​

Дополнительные настройки​

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

Тип поиска​

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

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

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

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

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

Тарифы​