Эта страница переведена с помощью 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` чтобы предотвратить откат.
`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
}