Эта страница переведена с помощью 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, если сигналы Wi-Fi и вышки сотовой связи отсутствуют, пусты или недостаточны для оценки местоположения устройства.	По умолчанию `true` . `considerIp` для параметра «false» значение `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
}