Запрос к геокодеру представляет собой обращение по HTTP-протоколу к URL http://geocode-maps.yandex.ru/1.x/.
Например, для того, чтобы определить координаты здания по адресу "ул. Тверская, дом 7" (здание Центрального Телеграфа в Москве), можно выполнить следующий запрос:
http://geocode-maps.yandex.ru/1.x/?geocode=Москва,+Тверская+улица,+дом+7&key=API-ключ
В ответ геокодер вернет географические координаты этого здания, а также дополнительную информацию о найденном объекте (см. результат запроса).
При обратном геокодировании в запросе указываются координаты искомого объекта, а в ответе будет возвращен его адрес.
Ниже в таблице приведен список параметров HTTP-запроса:
| Параметр |
Описание |
Пример |
|
Обязательные параметры
|
|
geocode
|
Адрес, который требуется геокодировать, либо географические координаты.
Координаты могут быть заданы в одном из следующих форматов.
|
Прямое геокодирование:
geocode=Москва,+Тверская+улица,+дом+7
Обратное геокодирование:
geocode=37.611,55.758
|
|
key
|
Ключ API Яндекс.Карт. |
key=API-ключ
|
|
Необязательные параметры
|
|
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 |
Географическая область поиска объекта.
Поиск может быть как ограничен данной областью, так и не ограничен (в зависимости от значения параметра ). В последнем случае использование параметров ll и spn влияет на порядок выдачи результата: объекты, находящиеся в данной области, являются приоритетными.
Формат записи
Параметр 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
|
|
rspn
|
Позволяет ограничить поиск объектов областью, заданной с помощью параметров ll и spn. Возможные значения:
- 0 - не ограничивать поиск (по умолчанию),
- 1 - ограничить.
|
rspn=1
|
|
results
|
Максимальное количество возвращаемых объектов.
Значение по умолчанию: 10.
|
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-US — американский;
- en-BR — английский;
- tr-TR — турецкий (только для карты Турции).
|
lang=en-US
|
Форматы записи географических координат
В HTTP-запросе к геокодеру географические координаты задаются параметром geocode. Значения координат указываются последовательно и разделяются пробелом, запятой или точкой с запятой. При этом слева и справа от символов-разделителей допускается произвольное количество пробелов.
Символ ";" нужно передавать в закодированном виде "%3B".
Для обозначения знака координат используются либо символы "+" и "-", либо буквы, определяющие соответствующие полушария Земли (использование символа "+" является необязательным). Например, для обозначения положительных координат используются N (северная широта) и E (восточная долгота), а отрицательных - W (западная долгота) и S (южная широта).
Знаки координат могут быть обозначены также и русскими буквами (С, В, З, Ю либо "с.ш.", "в.д.", "з.д." и "ю.ш." соответственно).
Буквы могут быть указаны как перед координатами, так и после: "В37.6176, С55.755" или "37.6176В, 55.755С". Также буквы могут отделяться пробелом: "В 37.6176, С 55.755".
Пример запроса для обратного геокодирования:
http://geocode-maps.yandex.ru/1.x/?geocode=E134.854,S25.828&key=API-ключ
Ниже приведен список допустимых форматов записи географических координат:
| Формат записи |
Порядок следования координат |
Пример |
| +-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 или С, В, З, Ю, либо "с.ш.", "в.д.", "з.д." и "ю.ш.".
Геокодер возвращает заданные координаты в элементе 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>
