地理位置要求
地理位置要求會使用 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 |
Wi-Fi 存取點物件的陣列。 | 請參閱下方的「WiFi 存取點物件」一節。 |
以下是 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 ) |
儲存格的專屬 ID。 | 對 radioType gsm (預設)、cdma 、wcdma 和 lte 為必要;nr 則為拒絕。請參閱下方的計算儲存格 ID 一節,其中也列出了各種無線電類型的有效值範圍。 |
newRadioCellId |
number (uint64 ) |
NR (5G) 儲存格的專屬 ID。 | radioType nr 為必填;其他類型則為 rejected。請參閱下方的計算 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 ) |
這個儲存格是主要儲存格後經過的毫秒數。 | 如果年齡為 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 Cell Identity (UC-ID),這是一個 28 位元整數值,用於串連 12 位元無線電網路控制器 ID (RNC-ID) 和 16 位元行動網路 ID (CID)。
公式:rnc_id << 16 | cid
。
有效範圍:0–268435455。
注意:如果在 WCDMA 網路中只指定 16 位元的行動網路 ID 值,可能會導致不正確或沒有任何結果。 - LTE (4G) 網路使用 E-UTRAN Cell Identity (ECI),這是一個串連 20 位元 E-UTRAN 節點 B ID (eNBId) 和 8 位元行動網路 ID (CID) 的 28 位元整數值。
公式:enb_id << 8 | cid
。
有效範圍:0–268435455。
注意:在 LTE 網路中,如果僅指定 8 位元行動網路 ID 值,可能會產生錯誤或零的結果。
在 API 要求中放置超出範圍的值可能會導致未定義的行為。Google 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, } ] }
Wi-Fi 存取點物件
要求主體的 wifiAccessPoints
陣列必須包含兩個以上的 Wi-Fi 存取點物件。macAddress
為必要欄位,所有其他欄位則為選填。
欄位 | JSON 類型 | 說明 | 附註 |
---|---|---|---|
macAddress |
string |
WiFi 節點的 MAC 位址。這項資訊通常稱為 BSS、BSSID 或 MAC 位址。 |
必要欄位。以半形冒號分隔 (: ) 的十六進位字串。
只有通用管理的 MAC 位址可透過 API 找出。系統會無訊息捨棄其他 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 為單位。 |
以下是 Wi-Fi 存取點物件的範例。
{ "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 等緩解措施。這個做法可以在應用程式需要位置估算的需求,以及其精確度和喚回度要求之間權衡取捨。下列篩選技術示範如何篩選輸入內容,但不要顯示身為應用程式工程師選擇套用的緩解措施。
本機管理的 MAC 位址對 API 來說不是實用的位置信號,因此會不發出通知,從要求中捨棄。如要移除這類 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,且通常用於網路管理和多點傳送功能,因此這些位址將不會做為位置信號使用。您也應從輸入內容中移除這些 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
。由於這份清單不到 2 個 Wi-Fi MAC 位址,因此要求不會成功,並會傳回 HTTP 404 (notFound
) 回應。
地理位置回應
成功的地理位置要求會傳回 JSON 格式的回應,定義位置和半徑。
location
:使用者預估的經緯度座標,以度為單位。包含一個lat
和一個lng
子欄位。accuracy
:大概位置的準確度 (以公尺為單位)。這個屬性代表指定location
周圍圓形的半徑。
{ "location": { "lat": 37.421875199999995, "lng": -122.0851173 }, "accuracy": 120 }