地理定位请求和响应

地理位置请求

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

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

您必须在请求中指定一个密钥，并将其作为 key 参数的值包含在内。A 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 节点 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 数组必须包含两个 或多个 WLAN 接入点对象，这些对象代表 物理上不同的 固定接入点设备。macAddress 字段是 必填字段。所有其他字段都是可选字段。 该服务会忽略移动的接入点 ，例如飞机和火车上的接入点。

下面展示了一个 WLAN 接入点对象示例，该对象是 请求正文的一部分， 如下所示。

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

舍弃未使用的 WiFi 接入点

移除 WiFi 接入点对象，其 macAddress 为 广播地址 (FF:FF:FF:FF:FF:FF) 或由 IANA 保留，可以提高使用 WiFi 作为 输入的 Geolocation API 调用的成功率。如果经过过滤后可以确定 Geolocation API 调用 不会成功，则可以使用一些缓解措施，例如使用较旧的位置信号或信号较弱的 WiFi 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。 由于此列表中的 WiFi MAC 地址少于 2 个，因此 请求不会成功，并且会返回 HTTP 404 (notFound) 响应。

地理位置响应

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

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

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

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

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