地理位置要求
系統會使用 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
陣列含有 0 個或多個行動通信基地台物件。
欄位 | JSON 類型 | 說明 | 附註 |
---|---|---|---|
cellId |
number (uint32 ) |
儲存格的專屬 ID。 | radioType gsm (預設)、cdma 、wcdma 和 lte 為必要;nr 則拒絕。請參閱下方的「計算儲存格 ID」一節,當中一併列出每個無線電類型的有效值範圍。 |
newRadioCellId |
number (uint64 ) |
NR (5G) 儲存格的專屬 ID。 | 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 ) |
自這個儲存格為主要儲存格以來的毫秒數。 | 如果年齡為 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 基地台 ID (ECI),這是 28 位元的整數值,與 20 位元的 E-UTRAN 節點 B (eNBId) 和 8 位元基地台 ID (CID) 串連。
公式: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 |
Wi-Fi 節點的 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": "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 存取點物件,可提升 Geolocation API 呼叫以 Wi-Fi 做為輸入內容的成功率。如果在篩選後確定無法成功進行 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 使用,且常用於網路管理和多點傳送函式,並會將其做為位置信號使用。您也應該從輸入至 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
。由於這份清單少於 2 個 Wi-Fi MAC 位址,因此要求不會成功,並且會傳回 HTTP 404 (notFound
) 回應。
「地理位置」回應
成功的地理位置要求會傳回 JSON 格式的回應,定義位置和半徑。
location
:使用者預估的經緯度座標,以度為單位。包含一個lat
和一個lng
子欄位。accuracy
:概略位置的精確度,以公尺為單位。這代表指定location
周圍的圓形半徑。
{ "location": { "lat": 37.421875199999995, "lng": -122.0851173 }, "accuracy": 120 }