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

Обращение к сервису производится с помощью GET-запроса по адресу https://search-maps.yandex.ru/v1/. Обязательными параметрами запроса являются: text, lang и apikey.

В ответ сервер возвращает найденные объекты, отсортированные по релевантности запросу. За один поисковый запрос можно получить не более 500 объектов.

https://search-maps.yandex.ru/v1/
 ? [apikey=<ключ>]
 & [text=<поисковый запрос>]
 & [type=<типы объектов>]
 & [lang=<язык ответа>]
 & [ll=<центр области поиска>]
 & [spn=<размеры области поиска>]
 & [bbox=<координаты области поиска>]
 & [rspn=<не искать за пределами области поиска>]
 & [results=<количество результатов в ответе>]
 & [skip=<количество пропускаемых результатов>]
 & [callback=<имя функции>]
Query-параметры
apikeyКлюч для доступа к сервису. Получение ключей и управление ими производится в кабинете разработчика.
text

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

Примеры (приведены без URL-кодирования):

text=лебединое озеро

text=55.750788,37.618534

text=Санкт-Петербург, ул. Блохина, 15

text=+7 495 739-70-70

text=ООО Яндекс

type

Типы возвращаемых результатов. Возможные значения:

  • geo — топонимы;
  • biz — организации;
  • не задано— автоматическое определения типа по тексту запроса.

Пример:

type=biz

langПредпочитаемый язык ответа. Задается в виде идентификатора локали в виде lang=language_region, где
  • language — двузначный код языка. Указывается в формате ISO 639-1. Задает язык, на котором будут отображаться названия найденных объектов;
  • region — двузначный код страны. Указывается в формате ISO 3166-1. Определяет региональные особенности, например единицу измерения (для обозначения расстояния до найденного объекта).
    Примечание. Для регионов RU, UA и TR расстояние показывается в километрах, для US — в милях.

Поддерживаемые значения:

  • ru_RU — русский;
  • uk_UA — украинский;
  • be_BY — белорусский;
  • en_RU — американский;
  • en_US — американский английский;
  • tr_TR — турецкий.

Если в значении параметра передается локаль, не входящая в этот список, сервис подбирает язык максимально близкий к заданному.

Пример: lang=uk_UA.

ll

Центр области поиска. Определяется с помощью долготы и широты, разделенных запятой. Долгота и широта указываются в градусах, представленных в виде десятичной дроби.

Используется совместно с параметром spn, определяющим размеры области поиска.

Игнорируется при обратном геокодировании.

Пример: ll=37.618920,55.756994&spn=0.552069,0.400552

spn

Размеры области поиска. Определяется с помощью протяженностей по долготе и широте, разделенных запятой. Протяженности указываются в градусах, представленных в виде десятичной дроби.

Используется совместно с параметром ll, определяющим центр области поиска.

Игнорируется при обратном геокодировании.

Пример: ll=37.618920,55.756994&spn=0.552069,0.400552

bbox

Альтернативный способ задания области поиска (см. ll+spn).

Границы области поиска задаются в виде географических координат (в последовательности «долгота, широта») левого нижнего и правого верхнего углов области.

Примечание. При одновременном задании bbox и ll+spn параметр bbox является более приоритетным.

Пример: bbox=36.83,55.67~38.24,55.91

rspn

Признак «жесткого» ограничения области поиска.

Если в области поиска (заданной с помощью параметров ll + spn либо bbox) ничего не найдено, сервис пытается найти результаты за ее пределами. Параметр rspn позволяет отключить поиск за пределами заданной области.

Возможные значения:

  • 0 — не ограничивать поиск. Используется по умолчанию.
  • 1 — не искать за пределами заданной области.
results

Количество возвращаемых объектов. По умолчанию — 10. Максимальное допустимое значение — 500.

Пример: results=25.

skip

Количество объектов в ответе (начиная с первого), которое необходимо пропустить.

Пример: skip=25.

callback

Имя JavaScript-функции, в которую будет передан ответ (в соответствии с соглашениями JSONP).

Пример: callback=my_response_handler