谷歌地图地理位置API解析

发表于:2017年5月9日

概观
Google Maps Geolocation API根据移动客户端可以检测到的单元塔和WiFi节点的信息返回位置和准确度半径。本文档描述了用于将此数据发送到服务器并向客户端返回响应的协议。

通过HTTPS使用POST完成通信。请求和响应都被格式化为JSON,并且两者的内容类型是 application/json。

在开始使用Geolocation API开发之前,请查看身份验证要求(需要API密钥)和 API使用限制。

地理位置请求

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

https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY
您必须在请求中指定一个键,作为参数的值 key。A key是您的应用程序的API密钥。此密钥标识您的应用程序以实现配额管理。了解如何获取密钥。

请求机构

请求正文必须格式为JSON。支持以下字段,所有字段都是可选的:

homeMobileCountryCode:设备家庭网络的移动国家代码(MCC)。
homeMobileNetworkCode:用于设备家庭网络的移动网络代码(MNC)。
radioType:移动广播类型。支持的值是 lte,gsm,cdma,和 wcdma。虽然此字段是可选的,但如果值可用,则应包含该字段,以获得更准确的结果。
carrier:载体名称。
considerIp:如果WiFi和信元塔信号不可用,指定是否回退到IP地理位置。请注意,请求头中的IP地址可能不是设备的IP。默认为true。设置 considerIp为false禁用回退。
cellTowers:一组细胞塔对象。请参阅下面的 单元塔对象部分。
wifiAccessPoints:一组WiFi接入点对象。请参阅下面的WiFi接入点对象 部分。


{
"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上,这是Cell ID(CID); CDMA网络使用基站ID(BID)。WCDMA网络使用连接无线网络控制器(RNC)和小区ID的32位值的UTRAN / GERAN小区标识(UC-Id)。在WCDMA网络中仅指定16位单元ID值可能会返回不准确的结果。
locationAreaCode(必需):GSM和WCDMA网络的位置区域代码(LAC)。CDMA网络的网络ID(NID)。
mobileCountryCode (必填):电台塔的移动国家代码(MCC)。
mobileNetworkCode(必填):电池塔的移动网络代码。这是GSM和WCDMA的MNC; CDMA使用系统ID(SID)。
当前未使用以下可选字段,但如果值可用,则可能包含以下可选字段。

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
    }
  ]
}

WiFi接入点对象

请求体的wifiAccessPoints数组必须包含两个或更多个WiFi接入点对象。macAddress是必须的; 所有其他字段都是可选的。

macAddress:(必填)WiFi节点的MAC地址。分隔符必须是:(冒号)。
signalStrength:当前信号强度以dBm为单位。
age:检测到此接入点以来的毫秒数。
channel:客户端与接入点通信的通道。
signalToNoiseRatio:目前的信噪比以dB为单位。
WiFi接入点对象示例如下所示。


{
 "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控制台中配置的 每用户限制的每秒请求数。应该配置此限制,以防止单个用户或小组用户排除您的每日配额,同时仍允许对所有用户进行合理访问。
notFound geolocation 404 请求有效,但没有返回任何结果。
parseError global 400 请求正文无效JSON。有关每个字段的详细信息,请参阅 请求正文部分。

示例请求

注意: Mac地址可能随时间而改变。因此,此页面上的示例可能会导致API中的错误消息。
如果您想使用示例数据尝试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位置API以及iOS设备使用 Google Places API for iOS从Android设备收集 信息。
经常问的问题

为什么accuracy我的地理位置回复中的半径很大?

如果您的地理位置响应在该accuracy领域显示出非常高的价值,则 该服务可能会根据请求IP而不是WiFi点或单元塔进行地理位置定位。如果没有单元塔或接入点有效或被识别,可能会发生这种情况。

要确认这是问题,设置considerIp到 false您的请求。如果响应是a 404,您已经确认您wifiAccessPoints和 您的cellTowers对象无法进行地理位置定位。