此页面由 Cloud Translation API 翻译。

地理定位请求和响应

地理位置请求

使用 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`	指定在 Wi-Fi 和手机基站信号缺失、空白或不充分估算设备位置时是否回退到 IP 地理定位。	默认为 `true`。将 `considerIp` 设置为 `false` 以防止回退。
`cellTowers`	`array`	移动电话基站对象的数组。	请参阅下文的手机基站对象部分。
`wifiAccessPoints`	`array`	WLAN 接入点对象的数组。	请参阅下文的 WiFi 接入点对象部分。

下面显示了一个 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`）	自从此小区成为主小区后经过的毫秒数。	如果年龄为 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 可自行决定截断数字，使其位于记录的范围内，推断对 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": "9c:1c:12:b0:45:f1",
  "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": "94:b4:0f:fd:c1:40",
      "signalStrength": -35,
      "signalToNoiseRatio": 0
    }
  ]
}

然后，您可以使用 c网址从命令行发出请求：

$ 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.4241876,
      "lng": -122.0917381
  },
  "accuracy": 32.839
}

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

移除具有在本地管理的 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。由于此列表具有少于 2 个 Wi-Fi MAC 地址，因此请求不会成功，并且系统会返回 HTTP 404 (notFound) 响应。

地理位置响应

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

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

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