地理定位请求和响应

地理位置请求

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

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

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

请求正文

请求正文必须采用 JSON 格式。如果未包含请求正文,系统将根据请求位置的 IP 地址返回结果。除非另有说明,否则以下字段均受支持,且所有字段均为选填字段:

字段 JSON 类型 说明 备注
homeMobileCountryCode numberuint32 设备的家庭网络的移动设备国家/地区代码 (MCC)。 支持 radioType gsm(默认)、wcdmaltenr;不用于 cdma
有效范围:0–999。
homeMobileNetworkCode numberuint32 设备家庭网络的移动网络代码。 这是用于 GSM、WCDMA、LTE 和 NR 的 MNC。
CDMA 使用系统 ID (SID)
MNC 的有效范围:0–999。
SID 的有效范围:0–32767。
radioType string 移动无线装置类型。支持的值包括 gsmcdmawcdmaltenr 虽然此字段是可选的,但如果客户端知道无线装置类型,则应该始终包含此字段。
如果省略此字段,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 numberuint32 小区的唯一标识符。 对于 radioType gsm(默认)、cdmawcdmalte 必需;对于 nr已被拒绝
请参阅下面的计算单元格 ID 部分,其中还列出了每种无线装置类型的有效值范围。
newRadioCellId numberuint64 NR (5G) 小区的唯一标识符。 对于 radioType nr必需的;对于其他类型,则会拒绝
请参阅下文的计算 newRadioCellId 部分,其中还列出了该字段的有效值范围。
locationAreaCode numberuint32 GSM 和 WCDMA 网络的位置区号 (LAC)。
CDMA 网络的网络 ID (NID)。
LTE 和 NR 网络的跟踪区号 (TAC)。
对于 radioType gsm(默认)和 cdma,是必需属性;对于其他值,则为可选。
包含 gsmcdmawcdmalte 的有效范围:0–65535。
nr 的有效范围:0–16777215。
mobileCountryCode numberuint32 手机基站的移动设备国家/地区代码 (MCC)。 对于 radioType gsm(默认)、wcdmaltenr 必需;不用于 cdma
有效范围:0–999。
mobileNetworkCode numberuint32 手机基站的移动网络代码。 这是用于 GSM、WCDMA、LTE 和 NR 的 MNC。
CDMA 使用系统 ID (SID)。
必填。
MNC 的有效范围:0-999。
SID 的有效范围:0–32767。

不使用下列可选字段,但如果有可用值,便可将其包括在内。

字段 JSON 类型 说明 备注
age numberuint32 自从此小区成为主小区后经过的毫秒数。 如果年龄为 0,则 cellIdnewRadioCellId 表示当前测量值。
signalStrength numberdouble 测量到的无线信号强度(以 dBm 为单位)。
timingAdvance numberdouble 时间提前值。

正在计算 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 结果,具体由 Google 自行决定。

以下是 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 地址。 必需。英文冒号分隔 (:) 的十六进制字符串。
通过该 API 只能找到通用管理的 MAC 地址。其他 MAC 地址则会被静默丢弃,可能会导致 API 请求实际变为空。如需了解详情,请参阅丢弃无用的 Wifi 接入点
signalStrength numberdouble 测量到的当前信号强度(以 dBm 为单位)。 对于 Wi-Fi 接入点,dBm 值通常为 -35 或更低,范围为 -128 到 -10 dBm。 请务必加上减号。
age numberuint32 自从检测到此接入点后经过的毫秒数。
channel numberuint32 客户端与接入点进行通信的信道。
signalToNoiseRatio numberdouble 当前信噪比(以 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
    }
  ]
}

然后,您可以使用 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.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 来移除此类 MAC 地址,例如,02:00:00:00:00:00 中的 2 表示的 1 位。广播 MAC 地址 (FF:FF:FF:FF:FF:FF) 就是一个本过滤器,本质上会被此过滤器排除的 MAC 地址示例。

00:00:5E:00:00:0000:00:5E:FF:FF:FF 之间的 MAC 地址范围为 IANA 预留,通常用于网络管理和多播功能,但不包括其用作位置信号。您还应从该 API 的输入中移除这些 MAC 地址。

例如,可以从名为 macsmacAddress 字符串数组中收集可用于地理定位的 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
}