此页面由 Cloud Translation API 翻译。

Switch to English

概览

简介

Geolocation API 会根据移动客户端可以检测到的有关手机基站和 Wi-Fi 节点的信息返回位置和精度半径。本文档介绍了用于向服务器发送此数据以及向客户端返回响应的协议。

使用 POST 通过 HTTPS 进行通信。请求和响应都采用 JSON 格式，并且两者的内容类型均为 application/json。

准备工作

在开始使用 Geolocation API 进行开发之前，请查看身份验证要求（您需要 API 密钥）和 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`	指定在 WLAN 和手机信号塔信号缺失、为空或不足以估计设备位置时，回退到 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 可能会截断号码（使其位于记录的范围内）、推断出对 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`	WiFi 节点的 MAC 地址。它通常称为 BSS、BSSID 或 MAC 地址。	必需。`:`（英文冒号）分隔的十六进制字符串。
`signalStrength`	`number` (`double`)	测量到的当前信号强度（以 dBm 为单位）。	对于 Wi-Fi 接入点，dBm 值通常不超过 -35 dBm，范围从 -128 dBm 到 -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
}

地理位置响应

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

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

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

错误

如果发生错误，系统会返回标准格式错误响应正文，并将 HTTP 状态代码设置为错误状态。

响应包含一个对象，该对象包含一个 error 对象，该对象具有以下键：

code：这与响应的 HTTP 状态相同。
message：错误的简短说明。
errors：已发生的错误的列表。每个错误都包含错误类型的标识符 (reason) 和简短说明 (message)。

例如，发送无效的 JSON 将返回以下错误：

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "parseError",
    "message": "Parse Error",
   }
  ],
  "code": 400,
  "message": "Parse Error"
 }
}

可能的错误包括：

原因	网域	HTTP 状态代码	说明
`dailyLimitExceeded`	`usageLimits`	403	您已超出每日上限。
`keyInvalid`	`usageLimits`	400	您的 API 密钥不适用于 Geolocation API。请确保您已添加了整个密钥，并且已购买 API，或已启用结算功能并激活 API 可免费获取配额。
`userRateLimitExceeded`	`usageLimits`	403	您已超出在 Google Cloud Console 中配置的请求限制。此限制通常设置为每天请求数、每 100 秒请求数和每位用户每 100 秒请求数。应配置此限制以防止单个或一小部分用户耗尽您的每日配额，同时仍允许所有用户合理访问。如需配置这些限制，请参阅限制 API 用量。
`notFound`	`geolocation`	404	请求有效，但未返回任何结果。
`parseError`	`global`	400	请求正文是无效的 JSON。如需详细了解每个字段，请参阅请求正文部分。

请求示例

如果您希望试用包含地理位置数据的 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
}

（如果您没有 API 密钥，请参阅获取 API 密钥。）

如需进一步测试，您可以使用 Places SDK for Android 和 Android Location API 从 Android 设备中收集信息，也可以使用 Places SDK for iOS 从 iOS 设备中收集信息。

常见问题解答

为什么我的地理位置响应中的 accuracy 半径非常大？

如果您的地理定位响应在 accuracy 字段中显示的值非常大，该服务可能会根据请求 IP（而不是 WiFi 点或手机基站）进行地理定位。如果没有有效的手机基站或接入点，或者没有有效的接入点或接入点，就可能会发生这种情况。

如需确认这是否就是问题所在，请将请求中的 considerIp 设置为 false。如果响应为 404，则表示您已确认 wifiAccessPoints 和 cellTowers 对象无法进行地理定位。