本頁面由 Cloud Translation API 翻譯而成。

地理位置要求與回應

地理位置要求

系統會使用 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 位址。

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
}

地理位置要求與回應