地理定位请求和响应

地理位置请求

使用 POST 将地理位置请求发送到以下网址：

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 的 MNC。
CDMA 使用系统 ID (SID)		 MNC 的有效范围：0-999。
SID 的有效范围：0-32767。
radioType string 移动无线网络类型。支持的值包括 gsm、cdma、wcdma、lte 和 nr。 虽然此字段是可选字段，但如果客户端知道无线电类型，则应始终包含此字段。
如果省略此字段，Geolocation API 会默认使用 gsm，如果假定的无线电类型不正确，则会导致无效或零结果。
carrier string 运营商名称。
considerIp boolean 指定当 WLAN 和移动电话基站信号缺失、为空或不足以估算设备位置时，是否回退到 IP 地理位置。 默认为 true。将 considerIp 设为 false 以防止回退。
cellTowers array 移动电话基站对象的数组。 请参阅下文的移动电话基站对象部分。
wifiAccessPoints array WLAN 接入点对象的数组。 请参阅下面的Wi-Fi 接入点对象部分。

Geolocation 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，遭拒。
请参阅下面的计算 cellId 部分，其中还列出了每种单选按钮类型的有效值范围。
newRadioCellId number（uint64） NR (5G) 小区的唯一标识符。 对于 radioType nr，此属性为必需；对于其他类型，此属性为被拒。
请参阅下面的计算 newRadioCellId 部分，其中还列出了该字段的有效值范围。
locationAreaCode number（uint32） GSM 和 WCDMA 网络的位置区域代码 (LAC)。
CDMA 网络的网络 ID (NID)。
LTE 和 NR 网络的跟踪区域代码 (TAC)。		 对于 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，这就是 MNC。
CDMA 使用的是系统 ID (SID)。		 必填。
移动网络运营商 (MNC) 的有效范围：0-999。
SID 的有效范围：0-32767。

系统不会使用以下可选字段，但如果有值，则可以包含这些字段。

字段 JSON 类型 说明 备注
age number（uint32） 自从此小区成为主小区后经过的毫秒数。 如果 age 为 0，cellId 或 newRadioCellId 就表示当前的测量值。
signalStrength number（double） 测量到的无线信号强度（以 dBm 为单位）。
timingAdvance number（double） 时间提前值。

计算 cellId

NR (5G) 之前的无线类型使用 32 位 cellId 字段将网络小区 ID 传递给 Geolocation API。

  • GSM (2G) 网络会按原样使用 16 位小区 ID (CID)。有效范围：0-65535。
  • CDMA (2G) 网络会按原样使用 16 位基站 ID (BID)。有效范围：0-65535。
  • WCDMA (3G) 网络使用 UTRAN/GERAN 小区 ID (UC-ID)，这是一个 28 位整数值，用于串联 12 位无线网络控制器标识符 (RNC-ID) 和 16 位小区 ID (CID)。
    公式：rnc_id << 16 | cid。
    有效范围：0-268435455。
    注意：在 WCDMA 网络中，如果只指定 16 位的小区 ID 值，则会导致结果不正确或为零。
  • LTE (4G) 网络使用 E-UTRAN 小区 ID (ECI)，这是一个 28 位整数值，由 20 位 E-UTRAN 节点 B 标识符 (eNBId) 和 8 位小区 ID (CID) 串联而成。
    公式：enb_id << 8 | cid。
    有效范围：0-268435455。
    注意：在 LTE 网络中，如果只指定 8 位的小区 ID 值，则会导致结果不正确或为零。

在 API 请求中放置超出这些范围的值可能会导致未定义的行为。API 可能会根据 Google 的判断截断数字，使其符合所记录的范围，推断出对 radioType 的更正，或者返回 NOT_FOUND 结果，而响应中不会显示任何指示器。

LTE 基站对象示例如下。

{
  "cellTowers": [
    {
      "cellId": 170402199,
      "locationAreaCode": 35632,
      "mobileCountryCode": 310,
      "mobileNetworkCode": 410,
      "age": 0,
      "signalStrength": -60,
      "timingAdvance": 15
    }
  ]
}

计算 newRadioCellId

小区 ID 长度超过 32 位的较新网络使用 64 位 newRadioCellId 字段将网络小区 ID 传递给 Geolocation API。

  • NR (5G) 网络会按原样使用 36 位新无线小区标识 (NCI)。
    有效范围：0-68719476735。

以下是 NR 移动电话基站对象的一个示例。

{
  "cellTowers": [
    {
      "newRadioCellId": 68719476735,
      "mobileCountryCode": 310,
      "mobileNetworkCode": 410,
      "age": 0,
      "signalStrength": -60,
    }
  ]
}

WLAN 接入点对象

请求正文的 wifiAccessPoints 数组必须包含两个或更多 WLAN 接入点对象，这些对象代表物理上不同的接入点设备。macAddress 是必需字段；所有其他字段均为可选字段。

字段 JSON 类型 说明 备注
macAddress string Wi-Fi 节点的 MAC 地址。通常称为 BSS、BSSID 或 MAC 地址。 必需。以英文冒号分隔的十六进制字符串 (:)。
只能通过 API 查找全球管理的 MAC 地址。系统会静默丢弃其他 MAC 地址，这可能会导致 API 请求实际上变为空。如需了解详情，请参阅舍弃无用的 Wi-Fi 接入点。
signalStrength number（double） 测量到的当前信号强度（以 dBm 为单位）。 对于 Wi-Fi 接入点，dBm 值通常为 -35 或更低，范围为 -128 到 -10 dBm。 请务必添加负号。
age number（uint32） 自从检测到此接入点后经过的毫秒数。
channel number（uint32） 客户端与接入点进行通信的信道。
signalToNoiseRatio number（double） 测量到的当前信噪比（以 dB 为单位）。

WLAN 接入点对象的一个示例如下。

{
  "macAddress": "f0:d5:bf:fd:12:ae",
  "signalStrength": -43,
  "signalToNoiseRatio": 0,
  "channel": 11,
  "age": 0
}

采样请求

如果您想尝试使用 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
}

舍弃未使用的 WLAN 接入点

移除具有本地管理 macAddress 的 Wi-Fi 接入点对象可以提高使用 Wi-Fi 作为输入的 Geolocation API 调用的成功率。 如果过滤后可以确定 Geolocation API 调用不会成功，则可以使用缓解措施，例如使用较旧的位置信号或信号较弱的 Wi-Fi AP。这种方法是在应用对位置估算的需求与其准确性和召回率要求之间进行权衡。以下过滤技术演示了如何过滤输入，但未显示您（作为应用工程师）可以选择应用的缓解措施。

本地管理的 MAC 地址对 API 而言不是有用的定位信号，并且会从请求中静默舍弃。您可以通过确保 macAddress 的最高有效字节的第二个最低有效位为 0（例如，02:00:00:00:00:00 中的 2 表示的 1 位）来移除此类 MAC 地址。广播 MAC 地址 (FF:FF:FF:FF:FF:FF) 就是一个很好的例子，说明此过滤器会排除哪些 MAC 地址。

00:00:5E:00:00:00 到 00:00:5E:FF:FF:FF 之间的 MAC 地址范围已预留给 IANA，通常用于网络管理和多播功能，因此无法用作位置信号。您还应从 API 的输入中移除这些 MAC 地址。

例如，您可以从名为 macs 的 macAddress 字符串数组中收集可用于地理定位的 MAC 地址：

Java
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")));
Python
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。由于此列表中的 Wi-Fi MAC 地址少于 2 个，因此请求将不会成功，系统会返回 HTTP 404 (notFound) 响应。

地理位置响应

成功的地理位置请求会返回 JSON 格式的响应，其中定义了位置和半径。

  • location：用户的估计纬度和经度坐标（以度为单位）。包含一个 lat 和一个 lng 子字段。
  • accuracy：预估位置的准确性（以米为单位）。这表示围绕给定 location 的圆的半径。
{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}