Google Maps Geolocation API

概览

Google Maps Geolocation API 根据移动客户端可以检测到的有关移动电话基站和 Wi-Fi 节点的信息返回位置和精度半径。本文档描述了用于将此数据发送到服务器并将响应返回给客户端的协议。

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

在开始使用 Geolocation API 进行开发前，请查看身份验证要求（需要 API 密钥）和 API 使用限额。

地理位置请求

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

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

您必须在请求中指定一个密钥，将其包括在内作为 key 参数的值。key 是您应用的 API 密钥。此密钥可以标识您的应用，以便进行配额管理。了解如何获取密钥。

请求正文

请求正文必须采用 JSON 格式。支持以下字段，并且所有字段都是可选的：

• homeMobileCountryCode：设备的家庭网络的移动国家代码 (MCC)。
• homeMobileNetworkCode：设备的家庭网络的移动网络代码 (MNC)。
• radioType：移动无线网络类型。支持的值有 lte、gsm、cdma 和 wcdma。虽然此字段是可选的，但如果提供了相应的值，就应该将此字段包括在内，以获得更精确的结果。
• carrier：运营商名称。
• considerIp：指定当 Wi-Fi 和移动电话基站的信号不可用时，是否回退到 IP 地理位置。请注意，请求头中的 IP 地址不能是设备的 IP 地址。默认为 true。将 considerIp 设置为 false 以禁用回退。
• cellTowers：移动电话基站对象的数组。请参阅下面的移动电话基站对象部分。
• wifiAccessPoints：Wi-Fi 接入点对象的数组。请参阅下面的 Wi-Fi 接入点对象部分。

{
  "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（必填）：小区的唯一标识符。在 GSM 上，这就是小区 ID (CID)；CDMA 网络使用的是基站 ID (BID)。WCDMA 网络使用 UTRAN/GERAN 小区标识 (UC-Id)，这是一个 32 位的值，由无线网络控制器 (RNC) 和小区 ID 连接而成。在 WCDMA 网络中，如果只指定 16 位的小区 ID 值，返回的结果可能会不准确。
• locationAreaCode（必填）：GSM 和 WCDMA 网络的位置区域代码 (LAC)。CDMA 网络的网络 ID (NID)。
• mobileCountryCode（必填）：移动电话基站的移动国家代码 (MCC)。
• mobileNetworkCode（必填）：移动电话基站的移动网络代码。对于 GSM 和 WCDMA，这就是 MNC；CDMA 使用的是系统 ID (SID)。

以下可选字段当前并未使用，但如果提供了相应的值，也可以将其包括在内。

• age：自从此小区成为主小区后经过的毫秒数。如果 age 为 0，cellId 就表示当前的测量值。
• signalStrength：测量到的无线信号强度（以 dBm 为单位）。
• timingAdvance：时间提前值。

以下是 GSM 移动电话基站对象的一个示例。

{
  "cellTowers": [
    {
      "cellId": 42,
      "locationAreaCode": 415,
      "mobileCountryCode": 310,
      "mobileNetworkCode": 410,
      "age": 0,
      "signalStrength": -60,
      "timingAdvance": 15
    }
  ]
}

以下是 WCDMA 移动电话基站对象的一个示例。

{
  "cellTowers": [
    {
      "cellId": 21532831,
      "locationAreaCode": 2862,
      "mobileCountryCode": 214,
      "mobileNetworkCode": 7
    }
  ]
}

Wi-Fi 接入点对象

请求正文的 wifiAccessPoints 数组必须包含两个或更多 Wi-Fi 接入点对象。macAddress 是必填的；所有其他字段都是可选的。

• macAddress：（必填）Wi-Fi 节点的 MAC 地址。分隔符必须为 :（冒号）。
• signalStrength：测量到的当前信号强度（以 dBm 为单位）。
• age：自从检测到此接入点后经过的毫秒数。
• channel：客户端与接入点进行通信的信道。
• signalToNoiseRatio：测量到的当前信噪比（以 dB 为单位）。

Wi-Fi 接入点对象的一个示例如下。

{
  "macAddress": "00:25:9c:cf:1c:ac",
  "signalStrength": -43,
  "age": 0,
  "channel": 11,
  "signalToNoiseRatio": 0
}

地理位置响应

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

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

{
  "location": {
    "lat": 51.0,
    "lng": -0.1
  },
  "accuracy": 1200.4
}

错误

在发生错误的情况下，系统将返回标准格式的错误响应正文，并将 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 密钥对于 Google Maps Geolocation API 无效。请确保您已加入了完整的密钥，而且您已购买该 API 或已启用收费和激活 API 以获得免费配额。
userRateLimitExceeded	usageLimits	403	您已超出自己在 Google API Console 中配置的每个用户每秒请求数限制。此限制应配置为防止单个或一小部分用户耗尽您每天的配额，同时还允许所有用户都能进行合理的访问。
notFound	geolocation	404	请求有效，但未返回任何结果。
parseError	global	400	请求正文不是有效的 JSON。请参阅请求正文部分以了解每个字段的详情。

请求示例

如果您想尝试使用 Google Maps Geolocation API 处理示例数据，请将以下 JSON 保存到一个文件中：

{
  "considerIp": "false",
  "wifiAccessPoints": [
    {
        "macAddress": "00:25:9c:cf:1c:ac",
        "signalStrength": -43,
        "signalToNoiseRatio": 0
    },
    {
        "macAddress": "00:25:9c:cf:1c:ad",
        "signalStrength": -55,
        "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": 33.3632256,
    "lng": -117.0874871
  },
  "accuracy": 20
}

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

为了进一步测试，您可以利用 Google Places API for Android 和 Android Location API 从您的 Android 设备收集信息，以及利用 Google Places API for iOS 从您的 iOS 设备收集信息。

常见问题解答

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

如果您的地理位置响应中 accuracy 字段的值非常大，该服务可能是根据请求 IP 而不是 Wi-Fi 点或移动电话基站来进行地理定位。如果没有有效的移动电话基站或接入点，或者未识别出任何移动电话基站或接入点，就可能会发生这种情况。

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