此页面由 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 接入点对象的数组。	请参阅下面的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`，遭拒。请参阅下面的计算 cellId 部分，其中还列出了每种单选按钮类型的有效值范围。
`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 小区 ID (UC-ID)，这是一个 28 位整数值，用于串联 12 位无线网络控制器标识符 (RNC-ID) 和 16 位小区 ID (CID)。
公式：rnc_id << 16 | cid。
有效范围：0-268435455。
注意：在 WCDMA 网络中，如果只指定 16 位的小区 ID 值，则会导致结果不正确或为零。
LTE (4G) 网络使用 E-UTRAN 小区 ID (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 位新无线小区 ID (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 地址。	必需。以英文冒号分隔的十六进制字符串 (`:`)。只能通过 API 查找全球管理的 MAC 地址。系统会静默丢弃其他 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 调用不会成功，则可以使用缓解措施，例如使用较旧的位置信号或信号较弱的 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。由于此列表中的 Wi-Fi MAC 地址少于 2 个，因此请求将不会成功，系统会返回 HTTP 404 (notFound) 响应。

地理位置响应

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

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

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