本頁面由 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 陣列含有零個或多個陣列行動通信基地台物件

欄位	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 Cell Identity (ECI)，此為 28 位元整數值將 20 位元 E-UTRAN 節點 B ID (eNBId) 和 8 位元行動網路 ID (CID) 串連起來。
公式：enb_id << 8 | cid。
有效範圍：0–268435455。
注意：如果在 LTE 網路中只指定 8 位元行動網路 ID 值，如果有錯誤或零結果

在 API 要求中放置超出範圍的值可能會導致未定義的行為。API Google 可自行斟酌將電話號碼截斷至規定的範圍內，推斷出修正為 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`)	目前訊號與雜訊的比率測量單位

以下是 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 較弱的信號可用此方法可在對位置估計以及其精確度和喚回度的需求 Google Cloud 就是最佳選擇下列篩選技術示範如何篩選，但請不要顯示您或許像應用程式一樣的可以選擇套用

本機管理的 MAC 位址對而且會從要求中直接捨棄。您可以移除這類 MAC 位址就必須確保 macAddress 中最重要的位元組是 0，例如這個 2 代表 1 位元， 02:00:00:00:00:00。廣播 MAC 位址 (FF:FF:FF:FF:FF:FF) 是 MAC 位址示例：可能會被這個篩選器排除

介於 00:00:5E:00:00:00 到 MAC 位址的範圍 00:00:5E:FF:FF:FF 是預訂，且通常用於網路管理和多點傳送功能這時就不能再當做地區信號使用建議您一併移除這些輸入至 API 的 MAC 位址。

舉例來說，您可以從名為 macs 的 macAddress 字串陣列：

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
}

地理位置要求與回應