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

JSON

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

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

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

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

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

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

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

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

{
   "common
[no-highlight[

Описание

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

Требуется

Да

]no-highlight]
": { "version
[no-highlight[

Описание

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

Требуется

Да

]no-highlight]
": "1.0", "api_key
[no-highlight[

Описание

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

Требуется

Да

]no-highlight]
": "ABM6WU0BAAAANfFuIQIAV1pUEYIBeogyUNvVbhNaJPWeM-AAAAAAAAAAAACRXgDsaYNpZWpBczn4Lq6QmkwK6g==" }, "gsm_cells
[no-highlight[

Описание

Массив объектов, каждый из которых описывает одну соту. Необходим хотя бы один объект в массиве.

Требуется

Нет

]no-highlight]
": [ { "countrycode
[no-highlight[

Описание

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

Требуется

Да

]no-highlight]
": 250, "operatorid
[no-highlight[

Описание

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

Требуется

Да

]no-highlight]
": 99, "cellid
[no-highlight[

Описание

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

Требуется

Да

]no-highlight]
": 42332, "lac
[no-highlight[

Описание

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

Требуется

Да

]no-highlight]
": 36002, "signal_strength
[no-highlight[

Описание

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

Требуется

Нет

]no-highlight]
": -80, "age
[no-highlight[

Описание

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

Требуется

Нет

]no-highlight]
": 5555 } ], "wifi_networks
[no-highlight[

Описание

Массив объектов, каждый из которых описывает одну точку доступа Wi-Fi. Необходим хотя бы один объект.

Требуется

Нет

]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]
": "00-1C-F0-E4-BB-F5", "signal_strength
[no-highlight[

Описание

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

Требуется

Нет

]no-highlight]
": -88, "age
[no-highlight[

Описание

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

Требуется

Нет

]no-highlight]
": 0, } ], "ip
[no-highlight[

Описание

Содержит IP-адрес.

Требуется

Нет

]no-highlight]
": { "address_v4
[no-highlight[

Описание

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

Требуется

Да

]no-highlight]
": "178.247.233.32" } }

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

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

Ответом является массив JSON следующего вида.

{
  "position
[no-highlight[

Описание

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

]no-highlight]
": { "latitude
[no-highlight[

Описание

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

]no-highlight]
": 55.743675, "longitude
[no-highlight[

Описание

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

]no-highlight]
": 37.5646301, "altitude
[no-highlight[

Описание

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

]no-highlight]
": 0.0, "precision
[no-highlight[

Описание

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

]no-highlight]
": 701.71643, "altitude_precision
[no-highlight[

Описание

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

]no-highlight]
": 30.0, "type
[no-highlight[

Описание

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

]no-highlight]
": "gsm" } }

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

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

  1. Не удалось обработать массив JSON.

    {
       "error": "JSON request is invalid"
    }

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

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

    {
       "error": "invalid api_key"
    }

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

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

    {
       "error": "Location not found"
    }

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

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

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

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

json={
   "common": {
      "version": "1.0",
      "api_key": "AAwkGkwBAAAA9muWLAMAKp9XjTBZtmOLeiBQJqHX6YEqNdUAAAAAAAAAAAAoEP1ZsBlcVFA_OpP55MK3Ek1r8A=="
   },
   "gsm_cells": [
       {
          "countrycode": 250,
          "operatorid": 99,
          "cellid": 42332,
          "lac": 36002,
          "signal_strength": -80,
          "age": 5555
       }
   ],
   "wifi_networks": [
       {
          "mac": "00-1C-F0-E4-BB-F5",
          "signal_strength": -88,
          "age": 0,
       }
       ,
       {
          "mac": "00904CC10000",
          "signal_strength": -87,
          "age": 0,
       }
   ],
   "ip": {
     "address_v4": "178.247.233.32"
   }
}

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

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

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

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


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

COMPRESSED BINARY DATA
--YYAANNDDEEXX--