Запрос геолокации и ответ

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

Запросы геолокации отправляются с помощью 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 для параметра «complit» значение false , чтобы предотвратить откат.
cellTowers array Массив объектов вышек сотовой связи. См. раздел «Объекты вышек сотовой связи» ниже.
wifiAccessPoints array Массив объектов точек доступа Wi-Fi. См. раздел «Объекты точек доступа 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 : 0–16777215.
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-адрес узла Wi-Fi. Обычно его называют BSS, BSSID или MAC-адресом. Необходимый. Шестнадцатеричная строка, разделенная двоеточиями ( : ).
Через API можно найти только MAC-адреса с универсальным администрированием . Другие MAC-адреса автоматически удаляются, что может привести к тому, что запрос API станет фактически пустым. Подробности см. в разделе Удаление ненужных точек доступа Wi-Fi .
signalStrength number ( double ) Текущая мощность сигнала измеряется в дБм. Для точек доступа Wi-Fi значения дБм обычно составляют -35 или ниже и варьируются от -128 до -10 дБм. Обязательно ставьте знак минус.
age number ( uint32 ) Количество миллисекунд с момента обнаружения этой точки доступа.
channel number ( uint32 ) Канал, по которому клиент взаимодействует с точкой доступа.
signalToNoiseRatio number ( double ) Текущее соотношение сигнал/шум измеряется в дБ.

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

{
  "macAddress": "f0:d5:bf:fd:12:ae",
  "signalStrength": -43,
  "signalToNoiseRatio": 0,
  "channel": 11,
  "age": 0
}

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

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

{
  "considerIp": "false",
  "wifiAccessPoints": [
    {
      "macAddress": "3c:37:86:5d:75:d4",
      "signalStrength": -35,
      "signalToNoiseRatio": 0
    },
    {
      "macAddress": "30:86:2d:c4:29:d0",
      "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.4241173,
    "lng": -122.0915717
  },
  "accuracy": 20
}

Удаление неиспользуемых точек доступа Wi-Fi

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

Локально администрируемые MAC-адреса не являются полезными сигналами местоположения для API и автоматически удаляются из запросов. Вы можете удалить такие MAC-адреса, убедившись, что второй младший бит старшего байта macAddress равен 0 , например 1 бит представлен 2 в 02:00:00:00:00:00 . Широковещательный MAC-адрес ( FF:FF:FF:FF:FF:FF ) является примером MAC-адреса, который можно было бы исключить с помощью этого фильтра.

Диапазон MAC-адресов между 00:00:5E:00:00:00 и 00:00:5E:FF:FF:FF зарезервирован для IANA и часто используется для управления сетью и функций многоадресной рассылки, что исключает их использование в качестве сигнала местоположения. . Вам также следует удалить эти MAC-адреса из входных данных API.

Например, MAC-адреса, пригодные для геолокации, можно получить из массива строк macAddress с именем macs :

Ява
String[] macs = {"12:34:56:78:9a:bc", "1c:34:56:78:9a:bc", "00:00:5e:00:00:01"};
ArrayList<String> _macs = new ArrayList<>(Arrays.asList(macs));
_macs.removeIf(m -> !(0 == (2 & Integer.parseInt(m.substring(1, 2), 16))
                      && !m.substring(0, 8).toUpperCase().equals("00:00:5E")));
    
Питон
macs = ['12:34:56:78:9a:bc', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01']
macs = [m for m in macs if (0 == (2 & int(m[1], 16)) and m[:8].upper() != '00:00:5E')]
    
JavaScript
macs = ['12:34:56:78:9a:bc', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01'];
macs = macs.filter(m => 0 === (2 & Number.parseInt(m[1], 16))
                           && m.substr(0, 8).toUpperCase() !== '00:00:5E');
    

Использование этого фильтра приводит к тому, что в списке остается только 1c:34:56:78:9a:bc . Поскольку в этом списке меньше двух MAC-адресов Wi-Fi , запрос не будет успешным и будет возвращен ответ HTTP 404 ( notFound ) .

Ответы по геолокации

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

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