地理定位请求和响应

地理位置请求

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

https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY

您必须在请求中指定一个密钥，并将其作为 key 参数的值。key 是应用的 API 密钥。此密钥用于标识您的应用，以便进行配额管理。了解如何获取密钥。

请求正文

请求正文必须采用 JSON 格式。如果未包含请求正文，系统会根据请求位置的 IP 地址返回结果。支持以下字段，除非另有说明，否则所有字段均为可选字段：

下面是一个 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 数组包含零个或多个手机基站对象。

以下可选字段不使用，但如果值可用，则可以包含。

正在计算 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 小区标识 (UC-ID)，这是一个 28 位整数值，由 12 位无线网络控制器标识符 (RNC-ID) 和 16 位小区 ID (CID) 串联而成。
  公式：rnc_id << 16 | cid。
  有效范围：0–268435455。
  注意：在 WCDMA 网络中，如果仅指定 16 位小区 ID 值，会导致结果不正确或结果为零。
• LTE (4G) 网络使用 E-UTRAN 小区标识 (ECI)，这是一个 28 位整数值，由 20 位 E-UTRAN Node B 标识符 (eNBId) 和 8 位小区 ID (CID) 串联而成。
  公式：enb_id << 8 | cid。
  有效范围：0–268435455。
  注意：在 LTE 网络中，如果仅指定 8 位小区 ID 值，会导致结果不正确或为零。

在 API 请求中放置超出这些范围的值可能会导致未定义的行为。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

较新的网络（其基站 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,
    }
  ]
}

对上述请求的响应如下所示：

{
  "location": {
    "lat": 37.7646157,
    "lng": -122.4127361
  },
  "accuracy": 1458.5570522410717
}

WLAN 接入点对象

请求正文的 wifiAccessPoints 数组必须包含两个或更多个 Wi-Fi 接入点对象，这些对象代表物理上不同的固定接入点设备。macAddress 字段是必填字段。所有其他字段都是选填字段。该服务会忽略移动的接入点，例如飞机和火车上的接入点。

下面显示了一个示例 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 接入点

移除 macAddress 为广播地址 (FF:FF:FF:FF:FF:FF) 或由 IANA 保留的 Wi-Fi 接入点对象，可以提高使用 Wi-Fi 作为输入的 Geolocation API 调用的成功率。如果在过滤后可以确定 Geolocation API 调用不会成功，则可以采取缓解措施，例如使用较旧的位置信号或信号较弱的 Wi-Fi AP。这种方法需要在应用对位置估算的需求与其精确率和召回率要求之间进行权衡。以下过滤技术演示了如何过滤输入，但未显示您作为应用工程师可能选择应用的缓解措施。

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

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

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")));
    

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')]
    

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。由于此列表包含的 Wi-Fi MAC 地址少于 2 个，因此请求不会成功，并且会返回 HTTP 404 (notFound) 响应。

地理位置响应

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

• location：用户的估算纬度和经度坐标（以度为单位）。包含一个 lat 和一个 lng 子字段。
• accuracy：估计位置的准确度（以米为单位）。这表示给定 location 周围圆圈的半径。

{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}

该 API 会根据输入信号返回位置和准确度半径。虽然该 API 可以返回高精确度的位置信息，但准确度可能会因可用信号的来源、数量、密度和强度而异。通常，您可以预期以下精确度半径：

• Wi-Fi 接入点：如果请求包含两个或更多 wifiAccessPoints，则返回的准确度半径通常约为 20 米。准确性会随着接入点数量的增加和信号强度的增强（以 dBm 为单位）而提高，信号强度通常在 -100 到 -20 dBm 之间。
• 手机基站：如果 Wi-Fi 信息不可用或不充分，API 会使用 cellTowers 来确定位置。准确性因手机基站类型、信号强度和网络密度而异：
  • 宏小区（最常见的类型，用于广域覆盖）提供的准确度较低。半径通常在几百米范围内，在手机基站覆盖范围稀疏的区域，半径可达几千米。对于宏小区，其精度半径通常不会低于 100 米。对于信号较强的手机基站，准确度通常较高。强信号通常为：LTE > -110 dBm（信号范围为 -140 至 -55 dBm）、WCDMA > -100 dBm（信号范围为 -111 至 -53 dBm）、CDMA > -100 dBm（信号范围为 -120 至 -40 dBm）以及 GSM > -80 dBm（信号范围为 -121 至 -1 dBm）。
  • 小型基站（例如毫微微蜂窝基站、微微蜂窝基站或室内中继器）可提供最精确的基于基站的位置信息，其精确度半径可在 10-30 米范围内。
• IP 地理定位：如果 considerIp 为 true，并且无法对任何 Wi-Fi 或手机基站信号进行地理定位，则该 API 会根据请求的 IP 地址估算位置。此方法提供的准确度最低，半径可能达到数千米。请参阅为什么精确度半径非常大？ 问题排查指南中的说明。