Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

地理位置要求與回應

地理位置要求

Geolocation 要求會使用 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 存取點物件陣列。	請參閱下方的「Wi-Fi 存取點物件」一節。

以下是 Geolocation API 要求主體範例。

{
  "homeMobileCountryCode": 310,
  "homeMobileNetworkCode": 410,
  "radioType": "lte",
  "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` 為拒絕。請參閱下方的「計算 cellId」一節，其中也列出每種無線電類型的有效值範圍。
`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 位元 Cell ID (CID)。有效範圍：0 至 65535。
CDMA (2G) 網路會直接使用 16 位元的基地台 ID (BID)。有效範圍：0 至 65535。
WCDMA (3G) 網路使用 UTRAN/GERAN 基地台 ID (UC-ID)，這是一個 28 位元整數值，串連 12 位元無線網路控制器 ID (RNC-ID) 和 16 位元基地台 ID (CID)。
公式：rnc_id << 16 | cid。
有效範圍：0 至 268435455。
注意：在 WCDMA 網路中，如果只指定 16 位元 Cell ID 值，會導致結果不正確或為零。
LTE (4G) 網路使用 E-UTRAN 基地台 ID (ECI)，這是一個 28 位元的整數值，串連 20 位元的 E-UTRAN 節點 B ID (eNBId) 和 8 位元的基地台 ID (CID)。
公式：enb_id << 8 | cid。
有效範圍：0 至 268435455。
注意：在 LTE 網路中，如果只指定 8 位元 Cell ID 值，會導致結果不正確或為零。

在 API 要求中輸入超出這些範圍的值，可能會導致未定義的行為。Google 可自行決定是否要讓 API 截斷數字，使其符合記錄的範圍、推斷 radioType 的修正值，或傳回 NOT_FOUND 結果，且回應中不含任何指標。

以下是 LTE 行動通信基地台物件範例，屬於要求主體的一部分。

{
  ...

  "cellTowers": [
    {
      "cellId": 170402199,
      "locationAreaCode": 35632,
      "mobileCountryCode": 310,
      "mobileNetworkCode": 410,
      "age": 0,
      "signalStrength": -60,
      "timingAdvance": 15
    }
  ]
}

上述要求的回應如下所示：

{
  "location": {
    "lat": 37.7801129,
    "lng": -122.4168229
  },
  "accuracy": 180.052
}

計算 `newRadioCellId`

較新的網路 (基地台 ID 長度超過 32 位元) 會使用 64 位元的 newRadioCellId 欄位，將網路基地台 ID 傳遞至 Geolocation API。

NR (5G) 網路會直接使用 36 位元的新無線電基地台 ID (NCI)。
有效範圍：0 至 68719476735。

以下是 NR 行動通信基地台物件範例，屬於要求主體的一部分。

{
  ...

  "cellTowers": [
    {
      "newRadioCellId": 68719476735,
      "mobileCountryCode": 310,
      "mobileNetworkCode": 410,
      "age": 0,
      "signalStrength": -60,
    }
  ]
}

上述要求的回應如下所示：

{
  "location": {
    "lat": 37.7646157,
    "lng": -122.4127361
  },
  "accuracy": 1458.5570522410717
}

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 之間。請務必加上減號。如果值大於 -10 dBm，API 會傳回 `NOT FOUND`。
`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
}

上述要求的回應如下所示：

{
  "location": {
    "lat": 37.7801129,
    "lng": -122.4168229
  },
  "accuracy": 180.052
}

要求範例

如要使用範例資料試用 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 為廣播地址 (FF:FF:FF:FF:FF:FF) 或由 IANA 保留的 Wi-Fi 存取點物件，可提高使用 Wi-Fi 做為輸入內容的 Geolocation API 呼叫成功率。如果經過篩選後，系統判定 Geolocation API 呼叫不會成功，則可採取緩解措施，例如使用舊的位置信號或信號較弱的 Wi-Fi AP。這種做法是在應用程式對位置估算的需求，以及精確度和喚回度要求之間取得平衡。下列篩選技術示範如何篩選輸入內容，但不會顯示您身為應用程式工程師，可能選擇採取的緩解措施。

00:00:5E:00:00:00 到 00:00:5E:FF:FF:FF 之間的 MAC 位址範圍保留給 IANA，通常用於網路管理和多點傳播功能，因此無法做為位置信號。此外，您也應從 API 的輸入內容中移除這些 MAC 位址。

舉例來說，您可以從名為 macs 的 macAddress 字串陣列中，收集可用於 Geolocation 的 MAC 位址：

Java

String[] macs = {"ff:ff:ff:ff:ff:ff", "1c:34:56:78:9a:bc", "00:00:5e:00:00:01"};
ArrayList<String> _macs = new ArrayList<>(Arrays.asList(macs));
_macs.removeIf(m -> !(!m.toUpperCase().equals("FF:FF:FF:FF:FF:FF")
                      && !m.substring(0, 8).toUpperCase().equals("00:00:5E")));

Python

macs = ['ff:ff:ff:ff:ff:ff', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01']
macs = [m for m in macs if (m.upper() != "FF:FF:FF:FF:FF:FF" and m[:8].upper() != '00:00:5E')]

JavaScript

macs = ['ff:ff:ff:ff:ff:ff', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01'];
macs = macs.filter(m => m.toUpperCase() !== "FF:FF:FF:FF:FF:FF"
                        && 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
}

API 會根據輸入信號傳回位置和精確度半徑。雖然 API 可傳回高精確度的位置，但精確度可能會因可用信號的來源、數量、密度和強度而異。一般來說，準確度半徑如下：

Wi-Fi 存取點：如果要求包含兩個以上的 wifiAccessPoints，傳回的精確度半徑通常約為 20 公尺。存取點數量越多、訊號越強 (以 dBm 為單位)，準確度就越高，訊號強度通常介於 -100 到 -20 dBm 之間。
行動通信基地台：如果 Wi-Fi 資訊無法使用或不足，API 會使用 cellTowers 判斷位置。準確度會因行動通信基地台類型、訊號強度和網路密度而有顯著差異：
- 巨型基地台 (最常見的類型，用於廣域覆蓋) 的準確度較低。半徑通常在數百公尺範圍內，在行動通信基地台覆蓋率稀疏的區域，半徑可達數千公尺。如果是巨型基地台，精確度半徑通常不會低於 100 公尺。一般來說，訊號強的行動通信基地台準確度較高。LTE 的強訊號通常 > -110 dBm (訊號範圍 -140 至 -55 dBm)、WCDMA > -100 dBm (訊號範圍 -111 至 -53 dBm)、CDMA > -100 dBm (訊號範圍 -120 至 -40 dBm)，以及 GSM > -80 dBm (訊號範圍 -121 至 -1 dBm)。
- 小型基地台 (例如毫微微型基地台、微微型基地台或室內中繼器) 可提供最精確的基地台位置，精確度半徑可達 10 到 30 公尺。
IP 地理定位：如果 considerIp 為 true，且無法透過 Wi-Fi 或行動通信基地台訊號進行地理定位，API 會根據要求的 IP 位址估算位置。這種方法的精確度最低，半徑可能達數千公尺。請參閱「為什麼精確度半徑非常大？」一節。請參閱疑難排解指南。

地理位置要求與回應 透過集合功能整理內容 你可以依據偏好儲存及分類內容。