地理定位请求和响应

地理位置请求

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

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

您必须在请求中指定键，并包含该键作为 key 参数。key 是应用的 API 密钥。此密钥用于标识您的应用，以便进行配额限制 管理。了解如何获取密钥。

请求正文

请求正文必须采用 JSON 格式。如果未加入请求正文， 根据请求位置的 IP 地址返回以下字段 且所有字段均为选填字段（除非另有说明）：

下面显示了一个 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 数组包含零个或多个 移动电话基站的物体。

未使用以下选填字段，但值 可用。

正在计算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
    }
  ]
}

正在计算 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 数组必须包含两个 一个或多个 Wi-Fi 接入点对象。macAddress 为必填项；全部 其他字段均为选填字段

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
}

丢弃未使用的 Wi-Fi 接入点

移除包含 macAddress 的 Wi-Fi 接入点对象 本地管理 可以提高使用 WiFi 作为输入的 Geolocation API 调用的成功率。 如果在过滤后可以确定 Geolocation API 调用 失败，相关缓解措施（例如使用较旧的位置信号或 也可以使用较弱的信号这种方法是 应用对位置估测及其精确率和召回率的需求 要求。以下过滤技术展示了如何过滤 但不要显示您可以采取的缓解措施， 选择申请。

本地管理的 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，通常用于网络管理和多播功能 这使得它们无法用作地理位置信号。您还应移除这些 从输入传送到 API 的 MAC 地址。

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

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

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
}