地理位置要求與回應

地理位置要求

系統會使用 POST 將地理位置要求傳送至下列網址:

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

您必須在要求中指定鍵,並將其視為 key 參數的值。key 是應用程式的 API 金鑰。為管理配額,此金鑰會識別您的應用程式。瞭解如何取得金鑰

要求主體

要求主體的格式必須採用 JSON 格式。如果未包含要求主體,則系統會根據要求位置的 IP 位址傳回結果。以下是系統支援的欄位,除非另有說明,否則所有欄位皆為選填:

欄位 JSON 類型 說明 附註
homeMobileCountryCode number (uint32) 裝置家用網路的行動裝置國家/地區代碼 (MCC)。 radioType gsm 支援 (預設值)、wcdmaltenr;不適用於 cdma
有效範圍:0–999。
homeMobileNetworkCode number (uint32) 裝置「家用」網路的行動網路代碼。 這是 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 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 (預設)、cdmawcdmalte必要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,此為必填屬性,其他值則為選填。
有效範圍包含 gsmcdmawcdmalte:0–65535。
有效範圍包含 nr:0–16777215。
mobileCountryCode number (uint32) 行動通信基地台的行動裝置國家/地區代碼 (MCC)。 radioType gsm (預設值)、wcdmaltenr必要;並非用於 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,cellIdnewRadioCellId 代表目前的測量結果。
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": "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 存取點物件,可提升 Geolocation API 呼叫以 Wi-Fi 做為輸入內容的成功率。如果在篩選後確定無法成功進行 Geolocation API 呼叫,就可以採用防護措施,例如使用較舊的位置信號或信號訊號較弱的 Wi-Fi AP。這種做法可在應用程式是否需要位置預估值,與精確度和喚回度需求之間取得取捨。下列篩選技術示範如何篩選輸入內容,但不會顯示應用程式工程師可以選擇套用的緩解措施。

本機管理的 MAC 位址對 API 來說不是實用的位置信號,因此會在要求中不顯示任何通知。如要移除這類 MAC 位址,請確保 macAddress 最不重要的第二個位元為 0,例如 02:00:00:00:00:002 代表的 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
}