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

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

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

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

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

Тело запроса

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

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

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

Вычисление 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 обязателен; все остальные поля являются необязательными.

Пример объекта точки доступа 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')]
    

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
}