Запросы геолокации
Запросы на определение геолокации отправляются методом 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 ) | Код мобильной сети для домашней сети устройства. Это код мобильной сети для 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": "lte", "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). | Обязательно для nr radioType ; для других типов не допускается .См. раздел «Вычисление 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 ) | Код мобильной сети вышки сотовой связи. Это код мобильной сети для 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), для передачи идентификатора сотовой сети в API геолокации используется 32-битное поле cellId .
- В сетях 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-битного значения идентификатора ячейки (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 бита, для передачи идентификатора сотовой сети в API геолокации используется 64-битное поле newRadioCellId .
- В сетях 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 }
объекты точек доступа 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 дБм. Обязательно указывайте знак минус. При значениях выше -10 дБм API возвращает NOT FOUND . |
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 }
Ответ на предыдущий запрос выглядит следующим образом:
{ "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 }
Удаление неиспользуемых точек доступа 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')]
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 . Поскольку в этом списке меньше 2 MAC-адресов Wi-Fi , запрос не будет успешным, и будет возвращен ответ HTTP 404 ( notFound ) .
Ответы геолокации
Успешный запрос на определение местоположения возвращает ответ в формате JSON, определяющий местоположение и радиус.
-
location: Предполагаемые пользователем координаты широты и долготы в градусах. Содержит одноlatи одно полеlng. -
accuracy: Точность определения местоположения в метрах. Это радиус круга вокруг заданногоlocation.
{ "location": { "lat": 37.421875199999995, "lng": -122.0851173 }, "accuracy": 120 }
API возвращает местоположение и радиус точности на основе входных сигналов. Хотя API может возвращать очень точное местоположение, точность может варьироваться в зависимости от источника, количества, плотности и мощности доступных сигналов. Обычно можно ожидать следующие радиусы точности:
- Точки доступа Wi-Fi : Если запрос включает две или более
wifiAccessPoints, радиус точности обычно составляет около 20 метров. Точность повышается с увеличением количества точек доступа и усилением сигнала (измеряемого в дБм), при этом уровень сигнала обычно колеблется от -100 до -20 дБм. - Сотовые вышки : Если информация о Wi-Fi недоступна или недостаточна, API использует данные о местоположении через
cellTowers. Точность значительно варьируется в зависимости от типа сотовой вышки, уровня сигнала и плотности сети:- Макросоты (наиболее распространенный тип, используемый для покрытия больших зон) обеспечивают более низкую точность. Радиус обычно составляет сотни метров и может достигать нескольких тысяч метров в районах с редким покрытием сотовых вышек. Для макросот редко удается достичь радиуса точности менее 100 метров. Точность, как правило, выше для сотовых вышек с сильным сигналом. Сильный сигнал обычно составляет > -110 дБм для LTE (диапазон сигнала от -140 до -55 дБм), > -100 дБм для WCDMA (диапазон сигнала от -111 до -53 дБм), > -100 дБм для CDMA (диапазон сигнала от -120 до -40 дБм) и > -80 дБм для GSM (диапазон сигнала от -121 до -1 дБм).
- Малые соты (например, фемтосоты, пикосоты или внутренние ретрансляторы) обеспечивают наиболее точное определение местоположения на основе сотовой связи, с радиусом точности, который может составлять от 10 до 30 метров.
- Геолокация по IP-адресу : Если
considerIpимеетtrueи невозможно определить местоположение по сигналам Wi-Fi или сотовой связи, API оценивает местоположение на основе IP-адреса запроса. Этот метод обеспечивает наименьшую точность, радиус определения местоположения может достигать тысяч метров. См. раздел «Почему радиус определения местоположения так велик?» в руководстве по устранению неполадок.