Google Maps Geolocation API

Обзор

Интерфейс Google Maps Geolocation API возвращает местоположение и радиус погрешности на основе информации от вышек сотовой связи и точек доступа Wi-Fi, которые может обнаружить мобильный клиент. В этом документе описывается протокол, с помощью которого можно передать эти данные на сервер и вернуть ответ клиенту.

Обмен данными осуществляется по протоколу HTTPS с использованием метода POST. Запрос и ответ представлены в формате JSON, а контент может иметь тип application или json.

Перед началом разработки с использованием Geolocation API проверьте требования аутентификации (необходим ключ API) и лимиты использования API.

Запросы данных геолокации

Запросы данных геолокации передаются с использованием метода POST по следующему URL-адресу:

https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY

Вам необходимо указать ключ в запросе, который добавлен как значение параметра key. key – это ключ API вашего приложения. Этот ключ используется для идентификации приложения в целях управления квотами. См. дополнительную информацию о получении ключа.

Основная часть запроса

Основная часть запроса должна быть представлена в формате JSON. Поддерживаются следующие поля, все они необязательны.

homeMobileCountryCode: код страны в системе мобильной связи (MCC) для домашней сети устройства.
homeMobileNetworkCode: код сети в системе мобильной связи (MNC) для домашней сети устройства.
radioType: тип мобильной радиосвязи. Поддерживаются следующие значения: lte, gsm, cdma и wcdma. Хотя это поле не является обязательным для заполнения, его необходимо использовать (при наличии значения), чтобы получить более точные результаты.
carrier: название поставщика услуг связи.
considerIp: указывает, следует ли возвращаться к геолокации по IP-адресу, если сигналы точек доступа Wi-Fi или вышек сотовой связи не обнаружены. Обратите внимание, что IP-адрес в заголовке запроса может не быть IP-адресом устройства. По умолчанию установлено значение true. Чтобы отключить такой возврат, установите для considerIp значение false.
cellTowers: массив объектов – вышки сотовой связи. См. далее раздел Объекты вышек сотовой связи.
wifiAccessPoints: массив объектов – точки доступа Wi-Fi. См. далее раздел Объекты точек доступа Wi-Fi.

{
  "homeMobileCountryCode": 310,
  "homeMobileNetworkCode": 410,
  "radioType": "gsm",
  "carrier": "Vodafone",
  "considerIp": "true",
  "cellTowers": [
    // See the Cell Tower Objects section below.
  ],
  "wifiAccessPoints": [
    // See the WiFi Access Point Objects section below.
  ]
}

Вышки сотовой связи

Массив cellTowers в основной части запроса содержит нулевое или большее количество объектов вышек сотовой связи.

cellId (обязательный параметр): уникальный идентификатор конкретной соты в сети. В сети стандарта GSM это идентификатор соты (CID); в сетях CDMA используется идентификатор основной станции (BID). В сетях WCDMA используется идентификатор соты UTRAN/GERAN (UC-Id), который представляет собой 32-разрядное значение, сочетающее в себе контроллер радиосети (RNC) и идентификатор соты. Указание только 16-разрядного идентификатора соты для сетей WCDMA может привести к неточным результатам.
locationAreaCode (обязательный параметр): код местоположения (LAC) для сетей GSM и WCDMA. Идентификатор сети (NID) для сетей CDMA.
mobileCountryCode (обязательный параметр): код страны в системе мобильной связи (MCC).
mobileNetworkCode (обязательный параметр): код сети в системе мобильной связи (MNC). Это код сети для GSM и WCDMA; в сети CDMA используется идентификатор системы (SID).

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

age: количество миллисекунд с того момента, когда эта сота была основной. Если этот параметр равен 0, текущее измерение будет представлено параметром cellId.
signalStrength: мощность радиосигнала, измеряемая в децибелах на милливатт (дБм).
timingAdvance: значение времени задержки распространения сигнала.

Ниже приведен пример объекта вышки сотовой связи в сети GSM.

{
  "cellTowers": [
    {
      "cellId": 42,
      "locationAreaCode": 415,
      "mobileCountryCode": 310,
      "mobileNetworkCode": 410,
      "age": 0,
      "signalStrength": -60,
      "timingAdvance": 15
    }
  ]
}

Ниже приведен пример объекта вышки сотовой связи в сети WCDMA.

{
  "cellTowers": [
    {
      "cellId": 21532831,
      "locationAreaCode": 2862,
      "mobileCountryCode": 214,
      "mobileNetworkCode": 7
    }
  ]
}

Объекты точек доступа Wi-Fi

Массив точек доступа wifiAccessPoints должен содержать не менее двух объектов точек доступа Wi-Fi. Параметр macAddress является обязательным, все остальные поля – дополнительные.

macAddress: (обязательный параметр) MAC-адрес узла Wi-Fi. Разделителем должен быть символ : (двоеточие).
signalStrength: текущая мощность сигнала, измеряемая в децибелах на милливатт (дБм).
age: количество миллисекунд с того момента, когда эта точка доступа был обнаружена.
channel: канал, по которому клиент взаимодействует с точкой доступа.
signalToNoiseRatio: отношение текущего сигнала к уровню шума, измеряемое в децибелах (дБ).

Ниже приведен пример точки доступа к сети Wi-Fi.

{
  "macAddress": "00:25:9c:cf:1c:ac",
  "signalStrength": -43,
  "age": 0,
  "channel": 11,
  "signalToNoiseRatio": 0
}

Ответы на запросы геолокационных данных

В успешном запросе геолокационных данных будет содержаться ответ в формате JSON с указанием местоположения и радиуса погрешности.

location: предполагаемые широта и долгота (в градусах), указанные пользователем. Содержит одно дополнительное поле lat и одно дополнительное поле lng.
accuracy: точность определения предполагаемого местоположения, указывается в метрах. Этот параметр представляет радиус круга вокруг указанного местоположения.

{
  "location": {
    "lat": 51.0,
    "lng": -0.1
  },
  "accuracy": 1200.4
}

Ошибки

В случае ошибки будет возвращен ответ на нее в стандартном формате, а для кода состояния HTTP будет установлено состояние ошибки.

Ответ будет содержать объект error со следующими ключами.

code: это то же самое, что и состояние HTTP ответа.
message: краткое описание ошибки.
errors: список возникших ошибок. Каждая ошибка содержит идентификатор типа ошибки (reason) и краткое описание (message).

Например, при отправке запроса, несоответствующего формату JSON, будет возвращена следующая ошибка:

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "parseError",
    "message": "Parse Error",
   }
  ],
  "code": 400,
  "message": "Parse Error"
 }
}

Возможные ошибки:

Причина	Домен	Код состояния HTTP	Описание
`dailyLimitExceeded`	`usageLimits`	403	Превышен суточный лимит.
`keyInvalid`	`usageLimits`	400	Ключ API недействителен для Google Maps Geolocation API. Убедитесь, что указан полностью весь ключ, и был приобретен API, или разрешена тарификация и активирован API, чтобы получить бесплатную квоту.
`userRateLimitExceeded`	`usageLimits`	403	Превышен лимит запросов в секунду для одного пользователя, указанный в Google API Console. Этот лимит необходимо настроить, чтобы не допустить расходования всей дневной квоты одним пользователем или небольшой группой пользователей, вместе с тем предоставляя всем пользователям разумные возможности доступа.
`notFound`	`geolocation`	404	Запрос составлен правильно, однако результаты не получены.
`parseError`	`global`	400	Основная часть запроса не соответствует формату JSON. См. раздел Основная часть запроса, чтобы получить информацию о каждом его поле.

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

Если вы планируете протестировать Google Maps Geolocation API с использованием демонстрационных данных, сохраните следующий запрос JSON в файл:

{
  "considerIp": "false",
  "wifiAccessPoints": [
    {
        "macAddress": "00:25:9c:cf:1c:ac",
        "signalStrength": -43,
        "signalToNoiseRatio": 0
    },
    {
        "macAddress": "00:25:9c:cf:1c:ad",
        "signalStrength": -55,
        "signalToNoiseRatio": 0
    }
  ]
}

После этого можно использовать инструмент cURL, чтобы выполнить запрос из командной строки:

$ curl -d @your_filename.json -H "Content-Type: application/json" -i "https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY"

Ответ для МАС-адресов выше выглядит следующим образом:

{
  "location": {
    "lat": 33.3632256,
    "lng": -117.0874871
  },
  "accuracy": 20
}

(Если у вас нет ключа API, см. раздел Получение ключа)

Для дополнительного тестирования можно собрать информацию от устройства Android при помощи Google Places API for Android и Android Location API, а также от устройства iOS при помощи Google Places API for iOS.

Часто задаваемые вопросы

Почему я получаю очень большой радиус погрешности (поле accuracy) в возвращаемых по запросу геолокационных данных?

Если ответ на ваш запрос геолокационных данных содержит очень большое значение в поле accuracy, служба может выполнять геолокационный поиск, учитывая IP-адрес отправки запроса вместо сведений о точках доступа Wi-Fi или вышках сотовой связи. Это может произойти, если вышки сотовой связи или точки доступа не соответствуют требуемым параметрам или не распознаются.

Чтобы подтвердить, что проблема заключается именно в этом, в своем запросе установите для параметра considerIp значение false. Если в ответе получено 404, это означает, что вы подтвердили, что геопоиск ваших объектов wifiAccessPoints и cellTowers невозможен.

Все готово!

Обзор

Запросы данных геолокации

Основная часть запроса

Вышки сотовой связи

Объекты точек доступа Wi-Fi

Ответы на запросы геолокационных данных

Ошибки

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

Часто задаваемые вопросы

Оставить отзыв о...

Все готово!

Активировать Google Maps Geolocation API

Google Maps Geolocation API

Обзор

Запросы данных геолокации

Основная часть запроса

Вышки сотовой связи

Объекты точек доступа Wi-Fi

Ответы на запросы геолокационных данных

Ошибки

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

Часто задаваемые вопросы

Оставить отзыв о...