地理定位请求和响应

地理位置请求

使用 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 指定在缺少 WiFi 和手机基站信号时是否回退到 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 自从此小区成为主小区后经过的毫秒数。 如果 age 为 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 可能会根据 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 位的新无线装置小区标识 (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 地址。 必需。以英文冒号分隔 (:) 的十六进制字符串。
仅限 普遍管理 MAC 地址可通过该 API 确定。其他 MAC 地址为 静默丢弃,可能会导致 API 请求 为空。有关详情,请参阅丢弃无用的 Wi-Fi 访问权限 积分
signalStrength numberdouble 测量到的当前信号强度(以 dBm 为单位)。 对于 Wi-Fi 接入点,dBm 值通常为 -35 或更低,范围为 -128 到 -10 dBm。 请务必添加减号。
age numberuint32 自从检测到此接入点后经过的毫秒数。
channel numberuint32 客户端与接入点进行通信的信道。
signalToNoiseRatio numberdouble 当前信噪比 以 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 调用 失败,相关缓解措施(例如使用较旧的位置信号或 也可以使用较弱的信号这种方法是 应用对位置估测及其精确率和召回率的需求 要求。以下过滤技术展示了如何过滤 但不要显示您可以采取的缓解措施, 选择申请。

本地管理的 MAC 地址对于 API 并从请求中静默删除它们。您可以移除此类 MAC 地址 方法是确保 macAddress 的最高有效字节是 0,例如该 1 位由 2 表示, 02:00:00:00:00:00。广播 MAC 地址 (FF:FF:FF:FF:FF:FF) 就是一个 MAC 地址示例, 从而有效地排除了这类数据

MAC 地址的范围,介于 00:00:5E:00:00:0000:00:5E:FF:FF:FF预留 适用于 IANA,通常用于网络管理和多播功能 这使得它们无法用作地理位置信号。您还应移除这些 从输入传送到 API 的 MAC 地址。

例如,可用于地理定位的 MAC 地址可从 由名为 macsmacAddress 字符串组成的数组:

<ph type="x-smartling-placeholder">
</ph>
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
}