地理位置请求
使用 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 |
指定在 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 |
number (uint32 ) |
小区的唯一标识符。 | 对于 radioType gsm (默认)、cdma 、wcdma 和 lte 是必需的;对于 nr ,则为 rejected。请参阅下文的计算单元格 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 |
Wi-Fi 节点的 MAC 地址。它通常称为 BSS、BSSID 或 MAC 地址。 |
必需。以英文冒号分隔 (: ) 的十六进制字符串。
该 API 只能找到通用管理的 MAC 地址。其他 MAC 地址会被静默丢弃,可能会导致 API 请求实际上变为空。如需了解详情,请参阅丢弃无用的 Wi-Fi 接入点。 |
signalStrength |
number (double ) |
测量到的当前信号强度(以 dBm 为单位)。 | 对于 Wi-Fi 接入点,dBm 值通常为 -35 或更低,范围为 -128 到 -10 dBm。请务必添加减号。 |
age |
number (uint32 ) |
自从检测到此接入点后经过的毫秒数。 | |
channel |
number (uint32 ) |
客户端与接入点进行通信的信道。 | |
signalToNoiseRatio |
number (double ) |
测量到的当前信噪比(以 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 调用不会成功,可以采用缓解措施,例如使用信号较旧的位置信号或信号较弱的 Wi-Fi AP。此方法会在应用的位置估算需求与精确率和召回率要求之间做出权衡。以下过滤方法演示了如何过滤输入,但并未显示作为应用工程师可以选择应用的缓解措施。
对于 API 而言,本地管理的 MAC 地址不是有用的位置信号,而是会从请求中静默丢弃。若要移除此类 MAC 地址,请确保 macAddress
的最高有效字节的第二有效位为 0
,例如 02:00:00:00:00:00
中的 2
表示的 1 位。例如,广播 MAC 地址 (FF:FF:FF:FF:FF:FF
) 可以被此过滤器有效排除的 MAC 地址。
00:00:5E:00:00:00
和 00:00:5E:FF:FF:FF
之间的 MAC 地址范围预留给 IANA,并通常用于网络管理和多播功能,而多播功能无法将其用作位置信号。您还应从 API 的输入中移除这些 MAC 地址。
例如,可以从名为 macs
的 macAddress
字符串数组中收集可用于地理定位的 MAC 地址:
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")));
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')]
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 }