Эта страница переведена с помощью Cloud Translation 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, если сигналы WiFi и вышек сотовой связи отсутствуют, пустые или недостаточны для оценки местоположения устройства.	Значение по умолчанию — `true` . Чтобы предотвратить откат, установите для `considerIp` значение `false` .
`cellTowers`	`array`	Массив объектов сотовой связи.	См. раздел «Объекты вышек сотовой связи» ниже.
`wifiAccessPoints`	`array`	Массив объектов точек доступа WiFi.	См. раздел «Объекты точек доступа WiFi» ниже.

Пример тела запроса 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` . См. раздел «Вычисление cellId» ниже, в котором также перечислены допустимые диапазоны значений для каждого типа радиоустройства.
`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-битного значения 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
    }
  ]
}

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

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

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

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