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

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

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

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

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

Текст запроса

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

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

{
  "homeMobileCountryCode": 310,
  "homeMobileNetworkCode": 410,
  "radioType": "lte",
  "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-битного значения Cell ID в сетях WCDMA приводит к неверным или нулевым результатам.
• В сетях LTE (4G) используется идентификатор соты E-UTRAN (ECI), представляющий собой 28-битное целое число, объединяющее 20-битный идентификатор узла B E-UTRAN (eNBId) и 8-битный идентификатор соты (CID).
  Формула: enb_id << 8 | cid .
  Допустимый диапазон: 0–268435455.
  Примечание: указание только 8-битного значения Cell ID в сетях LTE приводит к неверным или нулевым результатам.

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

Пример объекта сотовой вышки LTE, который является частью тела запроса , приведен ниже.

{
  ...

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

Ответ на предыдущий запрос выглядит так:

{
  "location": {
    "lat": 37.7801129,
    "lng": -122.4168229
  },
  "accuracy": 180.052
}

Расчет newRadioCellId

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

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

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

{
  ...

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

Ответ на предыдущий запрос выглядит так:

{
  "location": {
    "lat": 37.7646157,
    "lng": -122.4127361
  },
  "accuracy": 1458.5570522410717
}

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

Массив wifiAccessPoints в теле запроса должен содержать два или более объекта точек доступа Wi-Fi, представляющих физически отдельные стационарные устройства. Поле macAddress обязательно. Все остальные поля необязательны. Сервис игнорирует подвижные точки доступа, например, в самолётах и ​​поездах.

Пример объекта точки доступа WiFi, который является частью тела запроса , показан ниже.

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

Ответ на предыдущий запрос выглядит так:

{
  "location": {
    "lat": 37.7801129,
    "lng": -122.4168229
  },
  "accuracy": 180.052
}

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

Если вы хотите опробовать 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

Удаление объектов точек доступа 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
}