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

XML

Данные для определения местоположения и ответ имеют формат XML.

Краткое содержание

Запрос выполняется методом POST. Ниже показан URL запроса.

http://api.lbs.yandex.net/geolocation

Входные данные

В теле HTTP-запроса передается параметр xml, содержащий данные для определения местоположения.

Данные могут сжиматься методом gzip. В этом случае необходимо наличие параметра gzip в теле запроса (значение не важно), а запрос должен иметь тип «multipart/form-data» (см. Пример запроса с данными в сжатом виде).

Ниже показана структура, передаваемая в параметре xml (значения приведены для примера).

<ya_lbs_request
[no-highlight[

Описание

Корневой элемент

Требуется

Да

]no-highlight]
> <common
[no-highlight[

Описание

Содержит метаданные.

Требуется

Да

]no-highlight]
> <version
[no-highlight[

Описание

Версия API Яндекс.Локатор (в настоящее время — 1.0).

Требуется

Да

]no-highlight]
>1.0</version> <api_key
[no-highlight[

Описание

Уникальный ключ доступа к Яндекс.Локатор (получают на странице http://api.yandex.ru/maps/form.xml).

Требуется

Да

]no-highlight]
>ABM6WU0BAAAANfFuIQIAV1pUEYIBeogyUNvVbhNaJPWeM-AAAAAAAAAAAACRXgDsaYNpZWpBczn4Lq6QmkwK6g==</api_key> </common> <gsm_cells
[no-highlight[

Описание

Содержит один или несколько элементов cell с данными о сотах.

Требуется

Нет

]no-highlight]
> <cell
[no-highlight[

Описание

Содержит идентификационные коды одной соты. Дополнительно может содержать данные об уровне сигнала.

Требуется

Хотя бы один элемент

]no-highlight]
> <countrycode
[no-highlight[

Описание

Код страны (MCC, Mobile Country Code).

Требуется

Да

]no-highlight]
>250</countrycode> <operatorid
[no-highlight[

Описание

Код сети мобильной связи (MNC, Mobile Network Code).

Требуется

Да

]no-highlight]
>1</operatorid> <cellid
[no-highlight[

Описание

Идентификатор соты (CID, Cell Identifier).

Требуется

Да

]no-highlight]
>2294</cellid> <lac
[no-highlight[

Описание

Код местоположения (LAC, Location area code).

Требуется

Да

]no-highlight]
>6405</lac> <signal_strength
[no-highlight[

Описание

Уровень сигнала, измеренный в месте нахождения мобильного устройства. Отрицательное число, выраженное в «децибелах к милливатту» — dBm. Элемент зарезервирован для будущего использования.

Требуется

Нет

]no-highlight]
>-45</signal_strength> <age
[no-highlight[

Описание

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

Требуется

Нет

]no-highlight]
>1000</age> </cell> </gsm_cells> <wifi_networks
[no-highlight[

Описание

Содержит один или несколько элементов network с данными о точках доступа.

Требуется

Нет

]no-highlight]
> <network
[no-highlight[

Описание

Содержит MAC-адрес точки доступа. Дополнительно может содержать данные об уровне сигнала.

Требуется

Хотя бы один элемент

]no-highlight]
> <mac
[no-highlight[

Описание

MAC-адрес в символьном представлении. Байты могут разделяться дефисом, точкой, двоеточием или указываться слитно без разделителя, например: «12-34-56-78-9A-BC», «12:34:56:78:9A:BC», «12.34.56.78.9A.BC», «123456789ABC».

Требуется

Да

]no-highlight]
>12-34-56-78-9A-BC</mac> <signal_strength
[no-highlight[

Описание

Уровень сигнала, измеренный в месте нахождения мобильного устройства. Отрицательное число, выраженное в «децибелах к милливатту» — dBm. Элемент зарезервирован для будущего использования.

Требуется

Нет

]no-highlight]
>-90</signal_strength> <age
[no-highlight[

Описание

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

Требуется

Нет

]no-highlight]
>2000</age> </network> </wifi_networks> <ip
[no-highlight[

Описание

Содержит элемент address_v4.

Требуется

Нет

]no-highlight]
> <address_v4
[no-highlight[

Описание

IP-адрес мобильного устройства, назначенный оператором мобильного интернета.

Требуется

Да

]no-highlight]
>178.248.233.11</address_v4> </ip> </ya_lbs_request>

Если элементы gsm_cells, wifi_networks, ip отсутствуют в запросе, а также если предоставлены неверные данные, Яндекс.Локатор определяет местоположение по IP-адресу отправителя, взятому из заголовка IP-пакета. Этот адрес может быть подменен прокси-сервером, через который прошел IP-пакет, в результате чего местоположение может определиться неправильно.

Формат ответа

Ответом является XML-структура следующего вида.

<?xml version="1.0" encoding="UTF-8"?>
<ya_lbs_response
[no-highlight[

Описание

Корневой элемент

]no-highlight]
> <position
[no-highlight[

Описание

Содержит координату точки на местности в системе WGS-84 и другие данные.

]no-highlight]
> <latitude
[no-highlight[

Описание

Широта в градусах. Имеет десятичное представление с точностью до семи знаков после запятой.

]no-highlight]
>55.7351526</latitude> <longitude
[no-highlight[

Описание

Долгота в градусах. Имеет десятичное представление с точностью до семи знаков после запятой.

]no-highlight]
>37.5951196</longitude> <altitude
[no-highlight[

Описание

Высота над поверхностью мирового океана.

]no-highlight]
>0.0</altitude> <precision
[no-highlight[

Описание

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

]no-highlight]
>826.319232</precision> <altitude_precision
[no-highlight[

Описание

Максимальное отклонение от указанной высоты.

]no-highlight]
>30.0</altitude_precision> <type
[no-highlight[

Описание

Обозначение способа, которым определено местоположение: «gsm» — по сотам мобильных сетей, «wifi» — по точкам доступа Wi-Fi, «ip» — по IP-адресу.

]no-highlight]
>gsm</type> </position> </ya_lbs_response>

Сообщения об ошибках

Ниже перечислены возможные сообщения об ошибках.

  1. Не удалось обработать XML-данные.

    <?xml version="1.0" encoding="utf-8" ?>
    <ya_lbs_response>
      <error>XML request is invalid</error>
    </ya_lbs_response>

    Переданный XML имеет некорректную структуру, например отсутствуют обязательные элементы или закрывающие теги. Эта ошибка также возникает, если данные переданы в сжатом виде, но в запросе отсутствует параметр gzip.

  2. Неверный ключ для доступа к API.

    <?xml version="1.0" encoding="utf-8" ?>
    <ya_lbs_response>
      <error>invalid api_key</error>
    </ya_lbs_response>

    Необходимо получить ключ на странице http://api.yandex.ru/maps/form.xml.

  3. Невозможно определить местоположение.

    <?xml version="1.0" encoding="utf-8" ?>
    <ya_lbs_response>
      <error>Location not found</error>
    </ya_lbs_response>

    В сервисе отсутствуют сведения о сотах, точках доступа Wi-Fi, подсетях, владеющих IP-адресом. Также ошибка возникает, если данные имеют неверный формат, например вместо кодов соты передаются строки произвольной длины.

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

Запрос на определение местоположения по двум сотам, двум точкам доступа Wi-Fi и IP-адресу мобильного устройства.

POST /geolocation HTTP/1.1
Host: api.lbs.yandex.net
Accept-Encoding: identity
Content-length: 1078
Content-type: application/x-www-form-urlencoded

xml=<ya_lbs_request>
  <common>
     <version>1.0</version>
     <api_key>ABM6WU0BAAAANfFuIQIAV1pUEYIBeogyUNvVbhNaJPWeM-AAAAAAAAAAAACRXgDsaYNpZWpBczn4Lq6QmkwK6g==</api_key>
  </common>
  <gsm_cells>
     <cell>
        <countrycode>250</countrycode>
        <operatorid>2</operatorid>
        <cellid>34321</cellid>
        <lac>1237</lac>
        <signal_strength>-80</signal_strength>
     </cell>
     <cell>
        <countrycode>250</countrycode>
        <operatorid>2</operatorid>
        <cellid>12</cellid>
        <lac>1237</lac>
        <signal_strength>-80</signal_strength>    
        <age>1000</age>
     </cell>
  </gsm_cells>
  <wifi_networks>
     <network>
        <mac>12-34-56-78-9A-BC</mac>
        <signal_strength>-90</signal_strength>
        <age>2000</age>
     </network>
     <network>
        <mac>0123456789AB</mac>
        <signal_strength>-90</signal_strength>
     </network>
  </wifi_networks>
  <ip>
     <address_v4>178.248.233.11</address_v4>
  </ip>
</ya_lbs_request>

Пример запроса с данными в сжатом виде

Запрос имеет тип «multipart/form-data» и обязательно содержит параметр gzip (значение параметра не важно).

POST /geolocation HTTP/1.1
Host: api.lbs.yandex.net
Accept-Encoding: identity
Content-length: 633
Content-Type: multipart/form-data; boundary=YYAANNDDEEXX

--YYAANNDDEEXX
Content-Disposition: form-data; name="gzip"


--YYAANNDDEEXX
Content-Disposition: form-data; name="xml"
Content-Type: application/octet-stream
Content-Transfer-Encoding: binary

COMPRESSED BINARY DATA
--YYAANNDDEEXX--