地理定位请求和响应

地理位置请求

使用 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 指定在缺少 WiFi 和手机基站信号时是否回退到 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。
请参阅下面的计算单元格 ID 部分，其中也列出了 每个单选按钮类型的有效值范围
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 小区标识 (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 可能会根据 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 数组必须包含两个 一个或多个 Wi-Fi 接入点对象。macAddress 为必填项；全部 其他字段均为选填字段

字段 JSON 类型 说明 备注
macAddress string Wi-Fi 节点的 MAC 地址。它通常称为 BSS、BSSID 或 MAC 地址。 必需。以英文冒号分隔 (:) 的十六进制字符串。
仅限 普遍管理 MAC 地址可通过该 API 确定。其他 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
}

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

移除具有本地管理 macAddress 的 Wi-Fi 接入点对象可以提高使用 Wi-Fi 作为输入的 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 字符串组成的数组：

<ph type="x-smartling-placeholder">
</ph>
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
}