Эта страница переведена с помощью 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, если сигналы WiFi и вышек сотовой связи отсутствуют, пустые или недостаточны для оценки местоположения устройства.	Значение по умолчанию — `true` . Чтобы предотвратить откат, установите для `considerIp` значение `false` .
`cellTowers`	`array`	Массив объектов сотовой связи.	См. раздел « Объекты вышек сотовой связи» ниже.
`wifiAccessPoints`	`array`	Массив объектов точек доступа WiFi.	См. раздел « Объекты точек доступа WiFi» ниже.

Пример тела запроса 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` )	Количество миллисекунд с тех пор, как эта ячейка стала первичной.	Если 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-битного значения Cell ID в сетях 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 бит, используют 64-битное поле newRadioCellId для передачи идентификатора ячейки сети в API геолокации.

В сетях 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
}

Объекты точек доступа WiFi

Массив 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` )	Текущее отношение сигнал/шум измеряется в дБ.

Пример объекта точки доступа WiFi, который является частью тела запроса , показан ниже.

{
  ...
  
  "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
}

Удаление неиспользуемых точек доступа WiFi

Удаление объектов точек доступа 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
}

Запрос геолокации и ответ Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

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

Текст запроса

Объекты вышек сотовой связи

Вычисление cellId

Расчет newRadioCellId

Объекты точек доступа WiFi

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

Удаление неиспользуемых точек доступа WiFi

Ответы геолокации

Запрос геолокации и ответ

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

Расчет `newRadioCellId`