Запросы геолокации
Запросы геолокации отправляются с помощью 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 для параметра «complit» значение 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
, например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 }