Чтобы переводить контент на ваш предпочитаемый язык, Google использует технологии на основе искусственного интеллекта. Переводы от ИИ могут содержать ошибки.

Запрос и ответ на определение местоположения

Запросы данных геолокации

Запросы данных геолокации передаются с использованием метода 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`.	Это поле необязательное, но его следует заполнять, если тип радиомодуля известен клиенту. Если поле не заполнено, Geolocation API по умолчанию использует значение `gsm`. Это может привести к неверным или нулевым результатам, если предполагаемый тип радиосети указан неправильно.
`carrier`	`string`	название поставщика услуг связи.
`considerIp`	`boolean`	Указывает, следует ли использовать геолокацию по IP-адресу, если сигналы Wi-Fi и вышек сотовой связи отсутствуют, пусты или недостаточны для оценки местоположения устройства.	Значение по умолчанию – `true`. Задайте для параметра `considerIp` значение `false`, чтобы предотвратить возврат к предыдущей версии.
`cellTowers`	`array`	массив объектов – вышки сотовой связи.	Подробную информацию вы найдете в разделе Объекты вышек сотовой связи ниже.
`wifiAccessPoints`	`array`	массив объектов – точки доступа Wi-Fi.	Подробную информацию вы найдете в разделе Объекты точек доступа Wi-Fi ниже.

Ниже приведен пример тела запроса к Geolocation 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).	Обязательно для `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`)	количество миллисекунд с того момента, когда эта сота была основной.	Если возраст равен 0, то `cellId` или `newRadioCellId` представляет текущее измерение.
`signalStrength`	`number` (`double`)	мощность радиосигнала, измеряемая в децибелах на милливатт (дБм).
`timingAdvance`	`number` (`double`)	Значение опережения по времени.

Вычисление `cellId`

В типах радио до NR (5G) для передачи идентификатора соты сети в Geolocation API используется 32-битное поле cellId.

В сетях GSM (2G) используется 16-битный идентификатор CID. Допустимый диапазон: 0–65535.
В сетях CDMA (2G) используется 16-битный идентификатор базовой станции (BID). Допустимый диапазон: 0–65535.
В сетях WCDMA (3G) используется идентификатор UC-ID (UTRAN/GERAN Cell Identity), который представляет собой 28-битное целое число, объединяющее 12-битный идентификатор контроллера радиосети (RNC-ID) и 16-битный идентификатор соты (CID).
Формула: rnc_id << 16 | cid.
Допустимый диапазон: 0–268435455.
Примечание. Если в сетях WCDMA указать только 16-битное значение идентификатора соты, результаты будут неверными или нулевыми.
В сетях LTE (4G) используется идентификатор E-UTRAN Cell Identity (ECI) – 28-битное целое число, состоящее из 20-битного идентификатора E-UTRAN Node B Identifier (eNBId) и 8-битного идентификатора Cell ID (CID).
Формула: enb_id << 8 | cid.
Допустимый диапазон: 0–268435455.
Примечание. Если в сетях LTE указать только 8-битное значение идентификатора соты, результаты будут неверными или нулевыми.

Если в запросе к API указать значения, выходящие за пределы этих диапазонов, это может привести к неопределенному поведению. По усмотрению Google API может усечь число, чтобы оно соответствовало задокументированному диапазону, внести исправление в 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 бит, для передачи идентификатора соты в Geolocation API используется 64-битное поле newRadioCellId.

В сетях NR (5G) используется 36-битный идентификатор New Radio Cell Identity (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
}

Примеры запросов

Если вы хотите протестировать Geolocation 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, которые являются широковещательными адресами (FF:FF:FF:FF:FF:FF) или зарезервированы IANA, может повысить долю успешных вызовов Geolocation API, использующих Wi-Fi в качестве входных данных. Если после фильтрации становится понятно, что вызов Geolocation API не будет успешным, можно использовать более старые сигналы местоположения или точки доступа Wi-Fi с более слабыми сигналами. Этот подход представляет собой компромисс между потребностью вашего приложения в оценке местоположения и требованиями к точности и полноте. В примерах ниже показано, как фильтровать входные данные, но не показаны меры по устранению уязвимостей, которые вы можете применить как разработчик приложения.

Диапазон MAC-адресов от 00:00:5E:00:00:00 до 00:00:5E:FF:FF:FF зарезервирован для IANA и часто используется для управления сетью и многоадресной рассылки, поэтому не может применяться для определения местоположения. Также удалите эти MAC-адреса из входных данных API.

Например, MAC-адреса, которые можно использовать для геолокации, можно собрать из массива строк macAddress с именем macs:

Java

String[] macs = {"ff:ff:ff:ff:ff:ff", "1c:34:56:78:9a:bc", "00:00:5e:00:00:01"};
ArrayList<String> _macs = new ArrayList<>(Arrays.asList(macs));
_macs.removeIf(m -> !(!m.toUpperCase().equals("FF:FF:FF:FF:FF:FF")
                      && !m.substring(0, 8).toUpperCase().equals("00:00:5E")));

Python

macs = ['ff:ff:ff:ff:ff:ff', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01']
macs = [m for m in macs if (m.upper() != "FF:FF:FF:FF:FF:FF" and m[:8].upper() != '00:00:5E')]

JavaScript

macs = ['ff:ff:ff:ff:ff:ff', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01'];
macs = macs.filter(m => m.toUpperCase() !== "FF:FF:FF:FF:FF:FF"
                        && 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
}

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-адреса запроса. Этот метод обеспечивает наименьшую точность, радиус может составлять тысячи метров. Подробнее о том, почему радиус точности очень большой… в руководстве по устранению неполадок.