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

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

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

Запросы геолокации отправляются с помощью 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,
    }
  ]
}

Объекты точек доступа WiFi

Массив wifiAccessPoints тела запроса должен содержать два или более объектов точек доступа WiFi, представляющих физически различные устройства точек доступа. macAddress является обязательным; все остальные поля являются необязательными.

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

{
  "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
}

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

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

Локально администрируемые 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 . Поскольку в этом списке меньше 2 MAC-адресов WiFi , запрос не будет успешным и будет возвращен ответ HTTP 404 ( notFound ) .

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

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

• location : Оценочные координаты широты и долготы пользователя в градусах. Содержит одно подполе lat и одно lng .
• accuracy : Точность предполагаемого местоположения в метрах. Это представляет собой радиус окружности вокруг заданного location .

{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}