Документация

Параметры HTTP-запроса

Запрос к геокодеру представляет собой обращение по протоколу HTTPS к URL https://geocode-maps.yandex.ru/1.x/.

Например, для того чтобы определить координаты здания по адресу "ул. Тверская, дом 7" (здание Центрального Телеграфа в Москве), можно выполнить следующий запрос:

https://geocode-maps.yandex.ru/1.x/?geocode=Москва,+Тверская+улица,+дом+7

В ответ геокодер вернет географические координаты этого здания, а также дополнительную информацию о найденном объекте (см. результат запроса ).

При обратном геокодировании в запросе указываются координаты искомого объекта, а в ответе будет возвращен его адрес.

Примечание. В случае превышения суточного лимита запросов вместо результатов геокодирования сервис вернет статус 429.

Ниже в таблице приведен список параметров HTTP-запроса:

ПараметрОписаниеПример
Обязательные параметры
geocode

Адрес либо географические координаты искомого объекта.

Координаты могут быть заданы в одном из следующих форматов.

Прямое геокодирование:

geocode=Москва,+Тверская+улица,+дом+7

Обратное геокодирование:

geocode=37.611,55.758

apikey

Ключ, полученный в кабинете разработчика. Используется только в платной версии API.

apikey=Ahdb3kz...

Необязательные параметры
sco Порядок задания координат (только для обратного геокодирования). Возможные значения:
  • longlat - долгота, широта (по умолчанию);
  • latlong - широта, долгота.

Независимо от значения этого параметра в ответе геокодера координаты всегда будут возвращаться в последовательности «долгота широта».

Обратное геокодирование:

sco=latlong

kind Вид топонима (только для обратного геокодирования).

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

  • house - дом;
  • street - улица;
  • metro - станция метро;
  • district - район города;
  • locality - населенный пункт (город/поселок/деревня/село/...).

Обратное геокодирование:

kind=street

format

Требуемый формат ответа геокодера:

  • xml — результат возвращается в виде YMapsML-документа;
  • json — результат возвращается в формате JSON.

Значение по умолчанию: xml.

format=json
callback

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

Параметр учитывается только в том случае, если ответ возвращается в формате JSON.

callback=my_response_handler
ll+spn

Географическая область поиска объекта.

Поиск может быть как ограничен данной областью, так и не ограничен (в зависимости от значения параметра rspn
[no-highlight[

Описание

Позволяет ограничить поиск объектов областью, заданной с помощью параметров ll и spn либо bbox. Возможные значения:

  • 0 - не ограничивать поиск (по умолчанию),
  • 1 - ограничить.

Пример

rspn=1]no-highlight]
). В последнем случае заданная область может быть учтена при ранжировании.

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

Параметр ll задает долготу и широту центра области, а spn — ее протяженность (в градусах).

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

Обратное геокодирование

При обратном геокодировании параметр ll игнорируется, а spn учитывается, только если параметр kind принимает одно из следующих значений: house, street, locality или metro.

Прямое геокодирование:

ll=37.618920,55.756994&spn=0.552069,0.400552

Обратное геокодирование:

spn=0.552069,0.400552&kind=street
bbox

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

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

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

bbox=x1,y1~x2,y2

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

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

bbox=36.6,54.6~38.6,56.6
rspn

Позволяет ограничить поиск объектов областью, заданной с помощью параметров ll и spn либо bbox. Возможные значения:

  • 0 - не ограничивать поиск (по умолчанию),
  • 1 - ограничить.
rspn=1
results

Максимальное количество возвращаемых объектов.

Значение по умолчанию: 10.

Максимальное значение: 100.

results=5
skip Количество объектов в ответе (начиная с первого), которое необходимо пропустить. Значение по умолчанию: 0. skip=3
lang

Локаль.

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

lang=language_region, где

  • language — двузначный код языка. Указывается в формате ISO 639-1. Задает язык, на котором будут отображаться названия географических объектов.
  • region — двузначный код страны. Указывается в формате ISO 3166-1. Определяет региональные особенности.

Список поддерживаемых значений:

  • ru_RU — русский (по умолчанию);
  • uk_UA — украинский;
  • be_BY — белорусский;
  • en_RU — американский;
  • en_US — американский английский;
  • tr_TR — турецкий (только для карты Турции).
lang=en_US

key

Ключ API Яндекс.Карт. Используется в бесплатной версии API.

Ограничение. Если параметр key не передан, то поиск доступен только для следующих стран: Россия, Украина, Беларусь, Казахстан, Грузия, Абхазия, Южная Осетия, Армения, Азербайджан, Молдавия, Туркмения, Таджикистан, Узбекистан, Киргизия и Турция.

key=Av4tdh...

Форматы записи географических координат

В HTTP-запросе к геокодеру географические координаты задаются параметром geocode. Значения координат указываются последовательно и разделяются пробелом, запятой или точкой с запятой. При этом слева и справа от символов-разделителей допускается произвольное количество пробелов.

Примечание. Символ ";" нужно передавать в закодированном виде "%3B".

Для обозначения знака координат используются либо символы "+" и "-", либо буквы, определяющие соответствующие полушария Земли (использование символа "+" является необязательным). Например, для обозначения положительных координат используются N (северная широта) и E (восточная долгота), а отрицательных - W (западная долгота) и S (южная широта).

Знаки координат могут быть обозначены также и русскими буквами (С, В, З, Ю либо "с.ш.", "в.д.", "з.д." и "ю.ш." соответственно).

Буквы могут быть указаны как перед координатами, так и после: "В37.6176, С55.755" или "37.6176В, 55.755С". Также буквы могут отделяться пробелом: "В 37.6176, С 55.755".

Пример запроса для обратного геокодирования:

https://geocode-maps.yandex.ru/1.x/?geocode=E134.854,S25.828

Ниже приведен список допустимых форматов записи географических координат:
Формат записиПорядок следования координатПример
+-float, +-floatДолгота, широта134.854, -25.828
float [direction] *
[no-highlight[

* [direction] - буквенное обозначение одного из четырех направлений: N, E, W, S или С, В, З, Ю, либо “с.ш.“, “в.д.“, “з.д.“ и “ю.ш.“.

]no-highlight]
, float [direction]
ЛюбойE134.854, S25.828

134.854E, 25.828S

134.854в.д, 25.828ю.ш.

+-deg° mm' ss", +-deg° mm' ss"Широта, долгота-25°49′41.1″, 134°51′15.88″
deg° mm' ss" [direction], deg° mm' ss" [direction] Любой25°49′41.1″S, 134°51′15.88″E
NMEAЛюбой2549.67,S, 13451.26,E

* [direction] - буквенное обозначение одного из четырех направлений: N, E, W, S или С, В, З, Ю, либо "с.ш.", "в.д.", "з.д." и "ю.ш.".

Геокодер возвращает заданные координаты в элементе metaDataProperty/GeocoderResponseMetaData/Point/pos в формате "[долгота] [широта]":

<metaDataProperty>
    <GeocoderResponseMetaData>
        <request>E134.854,S25.828</request>
        <found>1</found>
        <results>10</results>
        <Point>
            <pos>134.854412 -25.828084</pos>
        </Point>
    </GeocoderResponseMetaData>
</metaDataProperty>