Перейти к основному содержимому

Поиск мест

API docs by Redocly

Каталог объектов (3.0)

2GIS API Support: api@2gis.ru URL: https://docs.2gis.com/

Каталог

Получение коллекции объектов

Осуществляет поиск мест по заданному запросу и выдаёт список результатов, разбитых на страницы.

query Parameters
key
required
string

Уникальный ключ пользователя API.

locale
string
Examples:
  • locale=ar_AE - Арабский язык для ОАЭ
  • locale=ru_RU - Русский язык для России

Локаль, с которой производится поиск и отдаются результаты.
Список доступных локалей:

  • az_AZ — азербайджанский (Азербайджан);
  • ru_AZ — русский (Азербайджан);
  • hy_AM — армянский (Армения);
  • ru_AM — русский (Армения);
  • ar_BH — арабский (Бахрейн);
  • en_BH — английский (Бахрейн);
  • ru_BY — русский (Беларусь);
  • ka_GE — грузинский (Грузия);
  • ru_GE — русский (Грузия);
  • en_EG — английский (Египет);
  • ar_EG — арабский (Египет);
  • it_IT — итальянский (Италия);
  • en_IQ — английский (Ирак);
  • ar_IQ — арабский (Ирак);
  • kk_KZ — казахский (Казахстан);
  • ru_KZ — русский (Казахстан);
  • en_QA — английский (Катар);
  • ar_QA — арабский (Катар);
  • en_CY — английский (Кипр);
  • es_CL — испанский (Кипр);
  • ky_KG — кыргызский (Кыргызстан);
  • ru_KG — русский (Кыргызстан);
  • en_CN — английский (Китай);
  • zh_CN — китайский (Китай);
  • ru_CN — русский (Китай);
  • en_KW — английский (Кувейт);
  • ar_KW — арабский (Кувейт);
  • en_MA — английский (Марокко);
  • ar_MA — арабский (Марокко);
  • en_AE — английский (ОАЭ);
  • ar_AE — арабский (ОАЭ);
  • en_OM — английский (Оман);
  • ar_OM — арабский (Оман);
  • en_RU — английский (Россия);
  • ar_RU — арабский (Россия);
  • es_RU — испанский (Россия);
  • it_RU — итальянский (Россия);
  • ru_RU — русский (Россия);
  • uk_RU — украинский (Россия);
  • cs_RU — чешский (Россия);
  • en_SA — английский (Саудовская Аравия);
  • ar_SA — арабский (Саудовская Аравия);
  • ru_TJ — русский (Таджикистан);
  • tg_TJ — таджикский (Таджикистан);
  • ru_UZ — русский (Узбекистан);
  • uz_UZ — узбекский (Узбекистан);
  • ru_UA — русский (Украина);
  • uk_UA — украинский (Украина);
  • cs_CZ — чешский (Чехия).

q
string [ 1 .. 500 ] characters

Произвольная поисковая строка.

type
Array of strings
Examples:
  • type=adm_div,street - Пример нескольких типов
  • type=adm_div - Пример единичного типа

Типы объектов, среди которых производится поиск. При передаче нескольких типов менее релевантные результаты одних типов могут вытесниться более релевантными других типов. Типы перечисляются через запятую.
Значение adm_div является псевдонимом для всех типов adm_div.* одновременно.
Список доступных типов:

  • branch — компания;
  • building — здание;
  • street — улица;
  • parking — парковка;
  • station — остановки или станция общественного транспорта;
  • station.metro — станция метро;
  • station_entrance — вход на станцию;
  • station_platform — остановочная платформа;
  • attraction — достопримечательность;
  • crossroad — перекрёсток;
  • gate — проход/проезд;
  • road — дорога;
  • route — маршрут;
  • adm_div — административная единица;
  • adm_div.city — город;
  • adm_div.country — страна;
  • adm_div.district_area — район области;
  • adm_div.district — район;
  • adm_div.division — округ;
  • adm_div.living_area — жилмассив, микрорайон;
  • adm_div.place — разные площадные объекты: парки, пляжи, территории баз отдыха, озёра и прочие места;
  • adm_div.region — регион (область/край/республика и т.п.);
  • adm_div.settlement — населённый пункт (деревня, посёлок и т.п.);
  • adm_div.amana — амана;
  • coordinates — глобальная координата в системе координат WGS84 в формате lon, lat;
  • coordinates_additional — дополнительная глобальная координата в системе координат WGS84 в формате lon, lat;
  • kilometer_road_sign — знак километра.

Список доступных подтипов (subtype) для разных типов объектов можно посмотреть в схеме ответа внутри items.

fields
Array of strings
Examples:
  • fields=items.region_id,items.name_ex - Пример нескольких типов
  • fields=items.region_id - Пример единичного типа

Дополнительные поля, которые необходимо отобразить в ответе, перечисляются через запятую. Поля с пометкой требуется дополнительное разрешение у ключа API будут присутствовать в выдаче только при выставленных разрешениях на это поле у ключа. По умолчанию ключ не имеет никакие из указанных дополнительных разрешений.
Список полей с информацией о геометрии и адресе места:

  • items.point — координаты объекта, заданные в системе координат WGS84 в формате lon, lat;
  • items.address — адрес, по которому располагается объект;
  • items.adm_div — принадлежность к административной территории;
  • items.full_address_name — адрес объекта с указанием города;
  • items.geometry.centroid — визуальный центр геометрии объекта;
  • items.geometry.hover — геометрия области, используемой для определения попадания курсора в зону объекта;
  • items.geometry.selection — геометрия для выделения объекта;

Список полей с дополнительной информацией о месте:
  • items.rubrics — категории компании;
  • items.org — организация, к которой относится филиал;
  • items.brand — бренд, к которому относится филиал;
  • items.contact_groups — контакты компании (требуется дополнительное разрешение у ключа API);
  • items.schedule — расписание работы компании;
  • items.schedule_special — особое расписание работы компании;
  • items.access_comment — локализованное название для типа доступа;
  • items.access — тип доступа для парковки;
  • items.capacity — вместимость парковки;
  • items.description — описание геообъекта;
  • items.external_content — дополнительные данные компании (требуется дополнительное разрешение у ключа API);
  • items.flags — список признаков объекта. Например, что для объекта есть фотографии, или что филиал временно не работает и т.д. Список доступных признаков можно посмотреть в схеме ответа внутри items;
  • items.floors — количество этажей (требуется дополнительное разрешение у ключа API);
  • items.floor_plans — планы этажей (требуется дополнительное разрешение у ключа API);
  • items.is_paid — является ли парковка платной;
  • items.for_trucks — парковка для грузовиков;
  • items.paving_type — тип покрытия парковки;
  • items.is_incentive — является ли парковка перехватывающей;
  • items.purpose — назначение парковки;
  • items.level_count — количество уровней парковки;
  • items.links — связанные объекты (ближайшие парковки, остановки общественного транспорта и другое);
  • items.links.database_entrances — информация о точках входа (требуется дополнительное разрешение у ключа API);
  • items.links.database_entrances.apartments_info — информация о квартирах в доме (требуется дополнительное разрешение у ключа API);
  • items.name_ex — составные части наименования объекта;
  • items.reviews — статистика по отзывам об объекте;
  • items.statistics — cводная информация о геообъекте;
  • items.employees_org_count — численность сотрудников организации (требуется дополнительное разрешение у ключа API);
  • items.itin — индивидуальный номер налогоплательщика (требуется дополнительное разрешение у ключа API);
  • items.trade_license — лицензия филиала (требуется дополнительное разрешение у ключа API);
  • items.fias_code — код ФИАС улиц и административных территорий (требуется дополнительное разрешение у ключа API);
  • items.address.components.fias_code — код ФИАС зданий (требуется дополнительное разрешение у ключа API);
  • items.fns_code — код ФНС административных территорий (требуется дополнительное разрешение у ключа API);
  • items.okato — код ОКАТО улиц и административных территорий (требуется дополнительное разрешение у ключа API);
  • items.address.components.okato — код ОКАТО зданий (требуется дополнительное разрешение у ключа API);
  • items.oktmo — код ОКТМО улиц и административных территорий (требуется дополнительное разрешение у ключа API);
  • items.address.components.oktmo — код ОКТМО зданий (требуется дополнительное разрешение у ключа API);

Список служебных полей:
  • context_rubrics — массив контекстных категорий;
  • dym — блок «Возможно, вы имели ввиду»;
  • filters — фильтры для дополнительного поиска;
  • hash — базовый хеш;
  • items.ads.options — рекламные опции;
  • items.attribute_groups — дополнительные атрибуты компании;
  • items.context — динамическая информация;
  • items.dates.deleted_at — дата удаления организации из базы в формате ISO 8601;
  • items.dates.updated_at — дата последнего изменения информации об организации в формате ISO 8601;
  • items.dates — время внесения информации о компании в БД;
  • items.geometry.style — идентификатор стиля для отображения;
  • items.group — связанные в объединённую карточку объекты;
  • items.metarubrics — метарубрики для выдачи организаций в гибридном объекте;
  • items.delivery — есть доставка;
  • items.has_goods — загружен список товаров фирмы;
  • items.has_pinned_goods — у фирмы включен блок «Закрепленные товары»;
  • items.has_realty — есть недвижимость на продаже;
  • items.has_audiogid — есть аудиогид у объекта;
  • items.has_discount — есть скидки;
  • items.has_exchange — признак наличия курсов валют у филиала;
  • items.is_main_in_group — признак того, что это главный объект в группе объектов гибрида;
  • items.city_alias — алиас города, в котором находится объект;
  • items.detailed_subtype — детализированный тип административно-территориальной единицы;
  • items.alias — транслитерированное название объекта;
  • items.caption — название объекта;
  • items.is_promoted — фирма участвует в промо-акции Чека;
  • items.routes — маршруты транспорта, проходящие через станцию или остановку;
  • items.directions — направления маршрута;
  • items.barrier — тип заграждения;
  • items.is_routing_available — флаг, возможен ли проезд до объекта;
  • items.entrance_display_name — показать номер входа на станцию метро, если объект является входом (station_entrance);
  • items.locale — текущая локаль для региона;
  • items.reg_bc_url — URL для регистрации бизнес-коннекшна просмотра профиля;
  • items.region_id — уникальный идентификатор проекта;
  • items.segment_id — уникальный идентификатор сегмента;
  • items.stat — данные для формирования сообщений статистики;
  • items.stop_factors — набор блокирующих атрибутов, соответствующих запросу;
  • items.has_apartments_info — признак наличия информации о квартирах в здании;
  • items.timezone — часовой пояс в формате POSIX;
  • items.timezone_offset — смещение таймзоны в минутах относительно UTC0;
  • items.comment — комментарий ко входу;
  • items.station_id — уникальный идентификатор остановки, к которой относится остановочная платформа;
  • items.platforms — остановочные платформы остановки;
  • items.sources — идентификатор источника данных об объекте;
  • items.structure_info.material — данные о материале здания (требуется дополнительное разрешение у ключа API);
  • items.structure_info.apartments_count — данные о количестве квартир в здании (требуется дополнительное разрешение у ключа API);
  • items.structure_info.porch_count — данные о количестве подъездов в здании (требуется дополнительное разрешение у ключа API);
  • items.structure_info.floor_type — тип перекрытий в здании (требуется дополнительное разрешение у ключа API);
  • items.structure_info.gas_type — тип газоснабжения здания (требуется дополнительное разрешение у ключа API);
  • items.structure_info.year_of_construction — год постройки здания (требуется дополнительное разрешение у ключа API);
  • items.structure_info.elevators_count — количество лифтов в здании (требуется дополнительное разрешение у ключа API);
  • items.structure_info.is_in_emergency_state — факт признания дома аварийным (требуется дополнительное разрешение у ключа API);
  • items.structure_info.project_type — серия/проект постройки здания (требуется дополнительное разрешение у ключа API);
  • items.structure_info.chs_name — название ОКН (объекта культурного наследия), требуется дополнительное разрешение у ключа API;
  • items.structure_info.chs_category — категория ОКН (требуется дополнительное разрешение у ключа API);
  • items.route_logo — иконка метро;
  • items.order_with_cart — свойства заказа у организации без доставки, но с корзиной;
  • items.is_deleted — признак удаленного объекта;
  • items.search_attributes — параметры результата поиска для найденного объекта. Каждое поле внутри items.search_attributes нужно запрашивать отдельно через точку, например, items.search_attributes.segment_id. Список доступных полей внутри объекта items.search_attributes можно посмотреть в схеме ответа для любого объекта внутри items;
  • items.congestion — загруженность филиала;
  • items.poi_category — категория POI;
  • items.has_dynamic_congestion — признак наличия онлайн значения текущей загруженности филиала;
  • items.temporary_unavailable_atm_services — признак наличия неработающих услуг у банкомата или терминала;
  • items.marker_alt — относительная высота размещения маркера;
  • items.floor_id — идентификатор этажа;
  • items.purpose_code — код назначения здания;
  • request_type — тип поискового запроса;
  • search_attributes — информация о произведённом поиске;
  • widgets — виджеты;
  • items.name_back — для дорожного знака локализованное название в обратном направлении при наличии;
  • items.value_back — для дорожного знака номер километра в обратном направлении;
  • items.ev_charging_station — аттрибуты электрозаправок;
  • items.ski_lift — информация о горнолыжном подъемнике;
  • items.has_ads_model — признак наличия рекламной 3D модели в здании;
  • items.has_otello_stories — признак наличия сторис от Отелло у филиала;
  • items.has_otello_hotels — признак наличия отелей в Отелло;
  • items.summary — блок обобщенной информации;

search_type
string
Default: "discovery"

Тип производимого поиска.
Допустимые значения:

  • discovery — максимально широкий поиск с возможностью раскрытия связанных объектов (категории, соответствующие запросу, будут раскрыты до входящих в них компаний);
  • one_branch — идентичен discovery, но для организации будет отдан только один филиал компании;
  • indoor — конфигурация для качественного поиска компаний в здании. Допускает поиск по префиксу, как подсказчик. Для отключения префикса используйте search_is_query_text_complete;
  • ads — идентичен discovery, но будут выданы только объекты с рекламой. Кроме того, для организации будет отдан только один первый по ранжированию филиал компании;
  • discovery_partial_searcher — идентичен discovery, но будет задействовано больше вариантов пересечений связей;
  • discovery_partial_searcher_strict — идентичен discovery_partial_searcher, но с выключенным префиксным поиском.

search_is_query_text_complete
boolean

Указание поисковому движку, что запрос является законченным (пользователь нажал на кнопку завершения ввода). Отключает префиксность, т.е. по "банк" не будет находиться "банкомат".

search_nearby
boolean

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

search_input_method
string

Указание поисковому движку способа ввода текста запроса:

  • hardware_qwerty_keyboard — физическая QWERTY-клавиатура
  • on_screen_keyboard — экранная touch screen клавиатура
  • voice — голосовой ввод
  • hand_writing — рукописный ввод
  • scanning — ввод который используется людьми с ограниченными возможностями. C помощью пальца или глазными движениями
  • software_generated — текст сгенерирован программным обеспечением
  • other — прочие типы ввода
sort
string
Default: "relevance"

Сортировка результатов. Допустимые значения:

  • distance — по возрастанию расстояния, если передан параметр sort_point, point или location (расстояние рассчитывается от переданной точки до геометрии объекта по кратчайшему пути), иначе — сортировка по типу объекта и его площади;
  • relevance — по убыванию релевантности. В поиске участвует название организации и категории, в которые входит организация. Учитывает максимум разных факторов: точность соответствия запроса объекту, популярность объектов, рейтинг, расположение, реклама и многое другое;
  • rating — по убыванию рейтинга;
  • flamp_rating — по убыванию рейтинга Флампа;
  • creation_time — по убыванию даты создания компании;
  • opened_time — по убыванию даты открытия;
  • name — по наименованию (в алфавитном порядке по возрастанию).

sort_point
string
Deprecated
Examples:
  • sort_point=82.921663,55.030195 - Долгота и широта

Координаты точки, от которой производится сортировка (координаты точки в формате lon, lat). Устаревший параметр, вместо него нужно использовать параметр location.

location
string
Examples:
  • location=82.921663,55.030195 - Долгота и широта

Координаты пользователя в формате lon, lat.

lon
string
Examples:
  • lon=82.921663 - Долгота

Долгота точки — центра области поиска.
Обязательно использование совместно с параметром lat.
Допустимый интервал значений: от -180 до 180.
Может использоваться совместно с параметром radius для фильтрации результатов в окружности.

lat
string
Examples:
  • lat=55.030195 - Широта

Широта точки — центра области поиска.
Обязательно использование совместно с параметром lon.
Допустимый интервал значений: от -90 до 90.
Может использоваться совместно с параметром radius для фильтрации результатов в окружности.

point
string
Examples:
  • point=82.921663,55.030195 - Долгота и широта

Центр области поиска (координаты точки в формате lon, lat).
Используется для фильтрации результатов в окружности. Параметр конфликтует с параметрами polygon, point1, point2.

radius
integer >= 0
Default: 250

Радиус поиска в метрах.
Ограничение: от 0 до 40000 — при наличии поискового запроса (q), от 0 до 2000 — при отсутствии.
Значение по умолчанию: 250 — в сочетании с point, 0 — в сочетании с lon/lat.
Используется для фильтрации результатов в окружности.

district_id
Array of integers
Examples:
  • district_id=141347373711435,141347373711473,141347373711478 - Пример нескольких идентификаторов
  • district_id=141347373711435 - Пример единичного идентификатора

Идентификаторы районов, разделённые запятыми. Используется для фильтрации объектов по району.
Максимальное количество — 50.

building_id
Array of integers
Examples:
  • building_id=141373143515660,141373143523268 - Пример нескольких идентификаторов
  • building_id=141373143515660 - Пример единичного идентификатора

Идентификаторы зданий, разделённые запятыми. Используется для фильтрации объектов в здании.
Максимальное количество — 50.

place_id
Array of integers
Examples:
  • place_id=141424683123045,141424683123024 - Пример нескольких идентификаторов
  • place_id=141424683123045 - Пример единичного идентификатора

Идентификаторы мест, разделённые запятыми. Используется для фильтрации объектов на территории.
Максимальное количество — 50.

city_id
Array of integers
Examples:
  • city_id=141373143515660,141373143523268 - Пример нескольких идентификаторов
  • city_id=141373143515660 - Пример единичного идентификатора

Идентификаторы городов, разделённые запятыми. Используется для фильтрации объектов по городу.
Максимальное количество — 50.

subway
Array of integers
Examples:
  • subway=141523467371731,141523467371220 - Пример нескольких идентификаторов
  • subway=141523467371731 - Пример единичного идентификатора

Идентификаторы станций метро, разделённые запятыми. Используется для фильтрации объектов по станциям метро.
Максимальное количество — 50.

point1
string
Examples:
  • point1=82.921663,55.030195 - Долгота и широта

Координаты левой верхней вершины прямоугольной области в формате lon, lat, ограничивающей результаты выборки.
Используется для фильтрации результатов в прямоугольной области.
Максимальное расстояние между точками point1 и point2 не более 2 км.
Если передан параметр q — ограничения не накладываются. Параметр конфликтует с параметрами point, polygon.

point2
string
Examples:
  • point2=82.921663,55.030195 - Долгота и широта

Координаты правой нижней вершины прямоугольной области в формате lon, lat, ограничивающей результаты выборки.
Используется для фильтрации результатов в прямоугольной области.
Максимальное расстояние между точками point2 и point1 не более 2 км.
Если передан параметр q — ограничения не накладываются. Параметр конфликтует с параметрами point, polygon.

polygon
string
Examples:
  • polygon=POLYGON((82.91259527206421 55.0614369017519,82.90572881698608 55.05902823221974,82.91521310806274 55.05580825372468,82.91259527206421 55.0614369017519)) - Формат WKT

Полигон в формате WKT.
Используется для фильтрации результатов в произвольной области. Допустимая площадь полигона ~ 6 км^2. Если передан параметр q — ограничения не накладываются. Параметр конфликтует с параметрами point, point1, point2.

viewpoint1
string
Examples:
  • viewpoint1=82.921663,55.030195 - Долгота и широта

Координаты левой верхней вершины прямоугольной области видимости в формате lon, lat. Параметры viewpoint1 и viewpoint2 передают область карты, куда смотрел пользователь перед вводом запроса. Используется как один из критериев для выбора, где нужны результаты, и для ранжирования. Не ограничивает жёстко результаты поиска только переданной областью.

viewpoint2
string
Examples:
  • viewpoint2=82.921663,55.030195 - Долгота и широта

Координаты правой нижней вершины прямоугольной области видимости в формате lon, lat. Параметры viewpoint1 и viewpoint2 передают область карты, куда смотрел пользователь перед вводом запроса. Используется как один из критериев для выбора, где нужны результаты, и для ранжирования. Не ограничивает жёстко результаты поиска только переданной областью.

region_id
integer

Идентификатор региона. Обязателен, если не задано географическое ограничение поиска. Подробности про территориальное деление карты на регионы можно посмотреть в описании Regions API.

page
integer [ 1 .. 1000000 ]
Default: 1

Номер запрашиваемой страницы.

page_size
integer [ 1 .. 50 ]
Default: 20

Количество результатов поиска, выводимых на одной странице.

rubric_id
Array of integers
Examples:
  • rubric_id=19290,360 - Пример нескольких записей
  • rubric_id=19290 - Пример единичной записи

Идентификатор категории. Необходимо передать параметр region_id.
Также можно передавать список идентификаторов категорий через запятую. В этом случае все категории должны быть из одного региона.

org_id
integer

Фильтр по идентификатору организации, к которой относится компания.

brand_id
integer

Фильтр по идентификатору бренда, к которому относится компания.

has_photos
boolean

Фильтр по наличию фотографий. Принимает значения: true или false.

has_rating
boolean

Фильтр по наличию рейтинга на flamp.ru. Принимает значения: true или false.

has_reviews
boolean

Фильтр по наличию отзывов на flamp.ru. Принимает значения: true или false.

has_site
boolean

Фильтр по наличию сайта. Принимает значения: true или false.

work_time
string
Examples:
  • work_time=now - Прямо сейчас
  • work_time=tue,alltime - Вторник, круглосуточно

Время работы организации. Формат: [day],[time] или now (текущий день и время).
Примеры:

  • Понедельник, 17:00 — mon,17:00
  • Четверг, 9:00 — thu,09:00
  • Сегодня, 9:00 — today,09:00
  • Пятница, весь день — fri,alltime
  • Сейчас — now

opened_after_date
string <date>
Examples:
  • opened_after_date=2007-09-03 - Позже чем 3 сентября 2007 года

Фильтрует компании у которых дата открытия позже чем переданный параметр.
Принимает значения в формате YYYY-MM-DD.

has_itin
boolean

Фильтр по наличию индивидуального номера налогоплательщика. Принимает значения: true или false.

has_trade_license
boolean

Фильтр по наличию торговой лицензии. Принимает значения true или false.

Responses

Response Schema: application/json
required
object (ObjMeta)

Метаданные ответа

required
object

Основной результат

Response samples

Content type
application/json
{
  • "meta": {
    • "api_version": "dev",
    • "issue_date": "string",
    • "code": 200
    },
  • "result": {
    • "items": [
      ],
    • "context_rubrics": [
      ],
    • "total": 1,
    • "search_attributes": {
      }
    }
}