Обзор

Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

Введение

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

Связь осуществляется по протоколу 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. Если тело запроса не включено, результаты будут возвращены на основе IP-адреса местоположения запроса. Поддерживаются следующие поля, и все поля являются необязательными, если не указано иное:

Поле Тип JSON Описание Заметки
homeMobileCountryCode number ( uint32 ) Мобильный код страны (MCC) для домашней сети устройства. Поддерживается для radioType gsm (по умолчанию), wcdma , lte и nr ; не используется для cdma .
Допустимый диапазон: 0–999.
homeMobileNetworkCode number ( uint32 ) Код мобильной сети для домашней сети устройства. Это MNC для GSM, WCDMA, LTE и NR.
CDMA использует идентификатор системы (SID).		 Допустимый диапазон для MNC: 0–999.
Допустимый диапазон для SID: 0–32767.
radioType string Тип мобильного радио. Поддерживаемые значения: gsm , cdma , wcdma , lte и nr . Хотя это поле является необязательным, оно всегда должно быть включено, если тип радиомодуля известен клиенту.
Если поле опущено, API геолокации по умолчанию будет использовать gsm , что приведет к неверным или нулевым результатам, если предполагаемый тип радио неверен.
carrier string Имя оператора.
considerIp boolean Указывает, следует ли возвращаться к геолокации IP, если сигналы Wi-Fi и вышек сотовой связи отсутствуют, пусты или недостаточны для оценки местоположения устройства. По умолчанию true . Установите для considerIp значение false , чтобы отключить откат.
cellTowers array Массив объектов вышек сотовой связи. См. раздел « Объекты вышек сотовой связи » ниже.
wifiAccessPoints array Массив объектов точки доступа WiFi. См. раздел « Объекты точки доступа Wi -Fi» ниже.

Пример тела запроса API геолокации показан ниже.

{
  "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 тела запроса содержит ноль или более объектов вышек сотовой связи.

Поле Тип JSON Описание Заметки
cellId number ( uint32 ) Уникальный идентификатор ячейки. Требуется для radioType gsm (по умолчанию), cdma , wcdma и lte ; отклонено для nr .
См. раздел « Вычисление идентификатора ячейки » ниже, в котором также перечислены допустимые диапазоны значений для каждого типа радио.
newRadioCellId number ( uint64 ) Уникальный идентификатор соты NR (5G). Требуется для radioType nr ; отклонены для других типов.
См. раздел « Вычисление newRadioCellId » ниже, в котором также указан допустимый диапазон значений для поля.
locationAreaCode number ( uint32 ) Код зоны местоположения (LAC) для сетей GSM и WCDMA.
Идентификатор сети (NID) для сетей CDMA.
Код зоны отслеживания (TAC) для сетей LTE и NR.		 Требуется для radioType gsm (по умолчанию) и cdma , необязателен для других значений.
Допустимый диапазон для gsm , cdma , wcdma и lte : 0–65535.
Допустимый диапазон с номером: nr .
mobileCountryCode number ( uint32 ) Мобильный код страны (MCC) вышки сотовой связи. Требуется для radioType gsm (по умолчанию), wcdma , lte и nr ; не используется для cdma .
Допустимый диапазон: 0–999.
mobileNetworkCode number ( uint32 ) Код мобильной сети вышки сотовой связи. Это MNC для GSM, WCDMA, LTE и NR.
CDMA использует идентификатор системы (SID).		 Необходимый.
Допустимый диапазон для MNC: 0–999.
Допустимый диапазон для SID: 0–32767.

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

Поле Тип JSON Описание Заметки
age number ( uint32 ) Количество миллисекунд, прошедших с тех пор, как эта ячейка стала основной. Если age равен 0, то cellId или newRadioCellId представляет текущее измерение.
signalStrength number ( double ) Мощность радиосигнала измеряется в дБм.
timingAdvance number ( double ) Значение опережения синхронизации .

Вычисление cellId

Типы радио до NR (5G) используют 32-битное поле cellId для передачи идентификатора соты сети в API геолокации.

  • Сети GSM (2G) используют 16-битный идентификатор соты (CID) как есть. Допустимый диапазон: 0–65535.
  • Сети CDMA (2G) используют 16-битный идентификатор базовой станции (BID) как есть. Допустимый диапазон: 0–65535.
  • В сетях WCDMA (3G) используется идентификатор соты UTRAN/GERAN (UC-ID), который представляет собой 28-битное целочисленное значение, объединяющее 12-битный идентификатор контроллера радиосети (RNC-ID) и 16-битный идентификатор соты (CID).
    Формула: rnc_id << 16 | cid .
    Допустимый диапазон: 0–268435455.
    Примечание. Указание только 16-битного идентификатора соты в сетях WCDMA приведет к неправильным результатам или к нулевым результатам.
  • Сети LTE (4G) используют идентификатор соты E-UTRAN (ECI), который представляет собой 28-битное целочисленное значение, объединяющее 20-битный идентификатор узла B E-UTRAN (eNBId) и 8-битный идентификатор соты (CID).
    Формула: enb_id << 8 | cid .
    Допустимый диапазон: 0–268435455.
    Примечание. Указание только 8-битного идентификатора соты в сетях LTE приведет к неправильным результатам или к нулевым результатам.

Размещение значений вне этих диапазонов в запросе API может привести к неопределенному поведению. API, по усмотрению Google, может обрезать число, чтобы оно соответствовало задокументированному диапазону, внести исправление в radioType или вернуть результат NOT_FOUND без какого-либо индикатора в ответе.

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

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

Вычисление newRadioCellId

Более новые сети, чьи идентификаторы ячеек длиннее 32 бит, используют 64-битное поле newRadioCellId для передачи идентификатора ячейки сети в API геолокации.

  • Сети NR (5G) используют 36-битный идентификатор новой радиосоты (NCI) как есть.
    Допустимый диапазон: 0–68719476735.

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

{
  "cellTowers": [
    {
      "newRadioCellId": 68719476735,
      "mobileCountryCode": 310,
      "mobileNetworkCode": 410,
      "age": 0,
      "signalStrength": -60,
    }
  ]
}

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

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

Поле Тип JSON Описание Заметки
macAddress string MAC-адрес узла WiFi. Обычно он называется BSS, BSSID или MAC-адресом. Необходимый. : (двоеточие) разделенная шестнадцатеричная строка.
signalStrength number ( double ) Текущий уровень сигнала измеряется в дБм. Для точек доступа WiFi значения дБм обычно составляют -35 или ниже и находятся в диапазоне от -128 до -10 дБм. Не забудьте поставить минус.
age number ( uint32 ) Количество миллисекунд с момента обнаружения этой точки доступа.
channel number ( uint32 ) Канал, по которому клиент взаимодействует с точкой доступа.
signalToNoiseRatio number ( double ) Текущее отношение сигнал/шум измеряется в дБ.

Пример объекта точки доступа Wi-Fi показан ниже.

{
  "macAddress": "9c:1c:12:b0:45:f1",
  "signalStrength": -43,
  "signalToNoiseRatio": 0,
  "channel": 11,
  "age": 0
}

Геолокационные ответы

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

  • location : расчетная широта и долгота пользователя в градусах. Содержит одно lat широты и одно lng .
  • accuracy : Точность предполагаемого местоположения в метрах. Это представляет собой радиус круга вокруг данного location .
{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}

Ошибки

В случае ошибки будет возвращено тело ответа об ошибке стандартного формата, а код состояния 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 недействителен для API геолокации. Убедитесь, что вы включили весь ключ и либо приобрели API, либо включили выставление счетов и активировали API , чтобы получить квоту бесплатно.
userRateLimitExceeded usageLimits 403 Вы превысили лимит запросов, который вы настроили в Google Cloud Console. Этот предел обычно устанавливается как количество запросов в день, запросов на 100 секунд и запросов на 100 секунд для каждого пользователя. Это ограничение должно быть настроено таким образом, чтобы предотвратить исчерпание вашей дневной квоты одной или небольшой группой пользователей, но при этом обеспечить разумный доступ для всех пользователей. См. раздел «Ограничение использования API» , чтобы настроить эти ограничения.
notFound geolocation 404 Запрос был действительным, но результаты не были возвращены.
parseError global 400 Тело запроса не является допустимым JSON. Подробнее о каждом поле см. в разделе « Тело запроса ».

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

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

{
  "considerIp": "false",
  "wifiAccessPoints": [
    {
      "macAddress": "3c:37:86:5d:75:d4",
      "signalStrength": -35,
      "signalToNoiseRatio": 0
    },
    {
      "macAddress": "94:b4:0f:fd:c1:40",
      "signalStrength": -35,
      "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"

Ответ для вышеуказанных адресов Mac выглядит так:

{
  "location": {
      "lat": 37.4241876,
      "lng": -122.0917381
  },
  "accuracy": 32.839
}

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

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

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

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

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

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