HTTP-запрос на геокодирование

Ставит задачу на прямое, либо обратное геокодирование.

  1. Формат запроса
  2. Формат записи географических координат в запросе
  3. Координаты запроса в ответе геокодера
  4. Пример запроса

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

https://geocode-maps.yandex.ru/1.x
 ? geocode=<string>
 & apikey=<string>
 & [sco=<string>]
 & [kind=<string>]
 & [rspn=<boolean>]
 & [ll=<number>, <number>]
 & [spn=<number>, <number>]
 & [bbox=<number>,<number>~<number>,<number>]
 & [format=<string>]
 & [skip=<integer>]
 & [lang=<string>]
 & [callback=<string>]
Query-параметры
geocode *
Адрес либо географические координаты искомого объекта. Указанные данные определяют тип геокодирования:
  • Если указан адрес, то он преобразуется в координаты объекта. Этот процесс называется прямым геокодированием.
  • Если указаны координаты, они преобразуются в адрес объекта. Этот процесс называется обратным геокодированием.

Доступны несколько форматов записи координат.

apikey *Ключ, полученный в Кабинете разработчика.
scoТолько если в параметре geocode указаны координаты. Порядок записи координат. Возможные значения:
  • longlat — долгота, широта;
  • latlong — широта, долгота.

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

kindТолько если в параметре geocode указаны координаты. Вид необходимого топонима.
Список допустимых значений:
  • house — дом;
  • street — улица;
  • metro — станция метро;
  • district — район города;
  • locality — населенный пункт (город/поселок/деревня/село/...).
Если параметр не задан, API выберет тип топонима автоматически.
rspn

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

  • 0 — не ограничивать поиск,
  • 1 — ограничивать поиск.

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

llДолгота и широта центра области поиска. Протяженность области поиска задается параметром spn.
Примечание. Если в параметре geocode указаны координаты, то параметр ll игнорируется.
spn

Протяженность области поиска. Центр области задается параметром ll.

Задается двумя числами:
  • первое обозначает разницу между максимальной и минимальной долготой области;
  • второе обозначает разницу между максимальной и минимальной широтой области.
Примечание. Если в параметре geocode указаны координаты и параметр kind имеет значение district, параметр spn не учитывается.
bbox

Альтернативный способ задания области поиска.

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

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

bbox=x1,y1~x2,y2
Примечание. При одновременном использовании параметров bbox и ll+spn, параметр bbox будет более приоритетным.

Игнорируется если в параметре geocode указаны координаты.

format

Формат ответа геокодера:

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

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

skipКоличество пропускаемых объектов в ответе, начиная с первого.

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

lang

Язык ответа и региональные особенности карты.

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

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

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

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

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

callback

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

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

Query-параметры
geocode *
Адрес либо географические координаты искомого объекта. Указанные данные определяют тип геокодирования:
  • Если указан адрес, то он преобразуется в координаты объекта. Этот процесс называется прямым геокодированием.
  • Если указаны координаты, они преобразуются в адрес объекта. Этот процесс называется обратным геокодированием.

Доступны несколько форматов записи координат.

apikey *Ключ, полученный в Кабинете разработчика.
scoТолько если в параметре geocode указаны координаты. Порядок записи координат. Возможные значения:
  • longlat — долгота, широта;
  • latlong — широта, долгота.

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

kindТолько если в параметре geocode указаны координаты. Вид необходимого топонима.
Список допустимых значений:
  • house — дом;
  • street — улица;
  • metro — станция метро;
  • district — район города;
  • locality — населенный пункт (город/поселок/деревня/село/...).
Если параметр не задан, API выберет тип топонима автоматически.
rspn

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

  • 0 — не ограничивать поиск,
  • 1 — ограничивать поиск.

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

llДолгота и широта центра области поиска. Протяженность области поиска задается параметром spn.
Примечание. Если в параметре geocode указаны координаты, то параметр ll игнорируется.
spn

Протяженность области поиска. Центр области задается параметром ll.

Задается двумя числами:
  • первое обозначает разницу между максимальной и минимальной долготой области;
  • второе обозначает разницу между максимальной и минимальной широтой области.
Примечание. Если в параметре geocode указаны координаты и параметр kind имеет значение district, параметр spn не учитывается.
bbox

Альтернативный способ задания области поиска.

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

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

bbox=x1,y1~x2,y2
Примечание. При одновременном использовании параметров bbox и ll+spn, параметр bbox будет более приоритетным.

Игнорируется если в параметре geocode указаны координаты.

format

Формат ответа геокодера:

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

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

skipКоличество пропускаемых объектов в ответе, начиная с первого.

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

lang

Язык ответа и региональные особенности карты.

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

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

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

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

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

callback

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

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

*  Обязательный параметр

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

Географические координаты в параметре geocode задаются последовательно в одном из следующих форматов:

Формат записи Порядок следования координат Пример
+-float, +-float Долгота, широта 134.854, -25.828

float [direction] , 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
Формат записи Порядок следования координат Пример
+-float, +-float Долгота, широта 134.854, -25.828

float [direction] , 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, или С, В, З, Ю, или "с.ш.", "в.д.", "з.д." и "ю.ш.". Между буквами и координатами допускаются пробелы.

Разделителем может быть пробел, запятая или точка с запятой. Слева и справа от символов-разделителей допускаются пробелы.

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

Координаты запроса в ответе геокодера

Геокодер возвращает заданные координаты в элементе 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>

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

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

https://geocode-maps.yandex.ru/1.x/?apikey=<Ваш API-ключ>&geocode=Москва,+Тверская+улица,+дом+7

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

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

https://geocode-maps.yandex.ru/1.x/?apikey=<Ваш API-ключ>&geocode=37.597576,55.771899

Дополнительные примеры доступны в разделе Примеры.