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

Маркеры

Спецификация OpenAPI
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 - Русский язык для России

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

Список доступных локалей:

  • ar_AE — арабский (ОАЭ);
  • ar_BH — арабский (Бахрейн);
  • ar_EG — арабский (Египет);
  • ar_IQ — арабский (Ирак);
  • ar_KW — арабский (Кувейт);
  • ar_MA — арабский (Марокко);
  • ar_OM — арабский (Оман);
  • ar_QA — арабский (Катар);
  • ar_RU — арабский (Россия);
  • ar_SA — арабский (Саудовская Аравия);
  • az_AZ — азербайджанский (Азербайджан);
  • az_RU — азербайджанский (Россия);
  • cs_CZ — чешский (Чехия);
  • cs_RU — чешский (Россия);
  • en_AE — английский (ОАЭ);
  • en_AM — английский (Армения);
  • en_AE — английский (ОАЭ);
  • en_BH — английский (Бахрейн);
  • en_CN — английский (Китай);
  • en_CY — английский (Кипр);
  • en_EG — английский (Египет);
  • en_IQ — английский (Ирак);
  • en_KW — английский (Кувейт);
  • en_MA — английский (Марокко);
  • en_MN — английский (Монголия);
  • en_OM — английский (Оман);
  • en_QA — английский (Катар);
  • en_RU — английский (Россия);
  • en_SA — английский (Саудовская Аравия);
  • en_TH — английский (Таиланд);
  • es_CL — испанский (Кипр);
  • es_RU — испанский (Россия);
  • hy_AM — армянский (Армения);
  • hy_RU — армянский (Россия);
  • it_IT — итальянский (Италия);
  • it_RU — итальянский (Россия);
  • ka_GE — грузинский (Грузия);
  • ka_RU — грузинский (Россия);
  • kk_KZ — казахский (Казахстан);
  • kk_RU — казахский (Россия);
  • ky_KG — кыргызский (Кыргызстан);
  • ky_RU — кыргызский (Россия);
  • mn_MN — монгольский (Монголия);
  • ru_AM — русский (Армения);
  • ru_AZ — русский (Азербайджан);
  • ru_BY — русский (Беларусь);
  • ru_CN — русский (Китай);
  • ru_GE — русский (Грузия);
  • ru_KG — русский (Кыргызстан);
  • ru_KZ — русский (Казахстан);
  • ru_RU — русский (Россия);
  • ru_TJ — русский (Таджикистан);
  • ru_UZ — русский (Узбекистан);
  • tg_RU — таджикский (Россия);
  • tg_TJ — таджикский (Таджикистан);
  • uz_RU — узбекский (Россия);
  • uz_UZ — узбекский (Узбекистан);
  • zh_CN — китайский (Китай).
fields
Array of strings
Examples:
  • fields=items.rubric_ids,items.floor_id - Пример нескольких полей
  • fields=items.rubric_ids - Пример единичного поля

Дополнительные поля, которые необходимо отобразить в ответе.

Список доступных полей:

  • items.rubric_ids — идентификаторы известных рубрик для объекта;
  • items.floor_id — идентификатор этажа;
  • items.name — название объекта;
  • items.trade_license — лицензия филиала;
q
required
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."

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 — прочие типы ввода
search_territory_of_interest
string
Example: search_territory_of_interest=MULTIPOLYGON (((87.17 53.75, 87.1789 53.75, 87.17 53.755, 87.177 53.75)))

Указание поисковому движку слабого ограничение на область поиска объектов: штраф за непопадание вместо строгого отбрасывания. Но вне TOI нет рекламы.

Требует формат WKT.

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

Идентификатор категории.

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

org_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.

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).

region_id
integer

Идентификатор региона.

Обязателен, если не задано географическое ограничение поиска.

Подробности про территориальное деление карты на регионы можно посмотреть в описании Regions API.

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

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

Максимальное количество — 50.

Может использоваться только совместно с параметром type=branch.

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.

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

Центр области поиска (координаты точки в формате lon, lat).

Используется для фильтрации результатов в окружности.

Параметр конфликтует с параметрами polygon, point1, point2.

radius
integer [ 0 .. 50000 ]
Default: 250

Радиус поиска в метрах.

Ограничение: от 0 до 50000 — при наличии поискового запроса (q, org_id, rubric_id, ip и т.п.), от 0 до 2000 — при отсутствии. Значение по умолчанию: 250 — в сочетании с point, 0 — в сочетании с lon/lat.

Используется для фильтрации результатов в окружности.

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 передают область карты, куда смотрел пользователь перед вводом запроса.

Используется как один из критериев для выбора, где нужны результаты, и для ранжирования. Не ограничивает жёстко результаты поиска только переданной областью.

page
integer [ 1 .. 1000000 ]
Default: 1

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

page_size
integer [ 1 .. 15000 ]
Default: 15000

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

Responses

Response Schema: application/json
One of
required
object

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

required
object

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

Response samples

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