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

Switch to English

總覽

簡介

Geolocation API 會根據行動用戶端可偵測到的行動通信基地台和 Wi-Fi 節點相關資訊，傳回地點和精確度半徑。本文件說明將這項資料傳送至伺服器並傳回用戶端回應的通訊協定。

這類通訊是透過 HTTPS 使用 POST 完成。要求和回應的格式均為 JSON，而兩者的內容類型為 application/json。

事前準備

開始使用 Geolocation API 開發前，請先詳閱驗證規定 (需要 API 金鑰) 和 API 用量與帳單資訊 (您需要為專案啟用計費功能)。

地理位置要求

地理位置要求透過 POST 傳送至下列網址：

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

您必須在要求中指定鍵，並納入 key 參數的值。key 是應用程式的 API 金鑰。此金鑰會識別應用程式，以進行配額管理。瞭解如何取得金鑰。

要求主體

要求內容的格式必須為 JSON。如果沒有要求主體，則會根據要求位置的 IP 位址傳回結果。系統會支援下列欄位，除非另有說明，否則所有欄位皆為選用欄位：

欄位	JSON 類型	說明	Notes
`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 類型	說明	Notes
`cellId`	`number` (`uint32`)	儲存格的專屬 ID。	對於 `radioType` `gsm` (預設)、`cdma`、`wcdma` 和 `lte` 而言，此為必填屬性；針對 `nr`，則為拒絕。請參閱下方的計算儲存格 ID 一節，其中會列出各圓形按鈕的有效值範圍。
`newRadioCellId`	`number` (`uint64`)	NR (5G) 儲存格的專屬 ID。	對於 `radioType` `nr` 而言，此為必填屬性；如果是其他類型，則為 reject。請參閱下方的計算 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 類型	說明	Notes
`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)，是包含 20 位元 E-UTRAN 節點 B ID (eNBId) 和 8 位元儲存格 ID (CID) 的 28 位元整數值。
公式：enb_id << 8 | cid。
有效範圍：0 至 268435455。
注意：如果在 LTE 網路中僅指定 8 位元儲存格 ID 的值，會導致錯誤或零的結果。

在 API 要求中放置超出範圍的值可能會導致未定義的行為。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。

下列的 RR 儲存格塔物件範例。

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

WiFi 存取點物件

要求主體的 wifiAccessPoints 陣列必須包含兩個以上的 Wi-Fi 存取點物件。macAddress 為必填欄位，其餘欄位則為選填。

欄位	JSON 類型	說明	Notes
`macAddress`	`string`	Wi-Fi 節點的 MAC 位址。這通常稱為 BSS、BSSID 或 MAC 位址。	必填。`:` (冒號) 是十六進位字串。
`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
}

地理位置回應

如果地理位置要求成功，系統會傳回定義位置和半徑的 JSON 格式回應。

location：使用者的預估緯度和經度 (以度為單位)。包含一個 lat 和一個 lng 子欄位。
accuracy：概略位置的精確度，以公尺為單位。這代表指定 location 的圓形半徑。

{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}

錯誤

如果發生錯誤，系統會傳回標準格式錯誤回應主體，並將 HTTP 狀態碼設為錯誤狀態。

回應中包含單一物件，當中包含下列 error 物件：

code：這與回應的 HTTP 狀態相同。
message：錯誤的簡短說明。
errors：發生錯誤的錯誤清單。每個錯誤都含有錯誤類型的 ID (reason) 和簡短說明 (message)。

舉例來說，傳送無效的 JSON 會傳回下列錯誤：

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "parseError",
    "message": "Parse Error",
   }
  ],
  "code": 400,
  "message": "Parse Error"
 }
}

可能出現的錯誤如下：

原因	網域	HTTP 狀態碼	說明
`dailyLimitExceeded`	`usageLimits`	403	您已超過每日上限。
`keyInvalid`	`usageLimits`	400	您的 API 金鑰無法用於 Geolocation API。請確認您已加入整個金鑰，並已購買 API 或啟用計費功能並啟用 API，才能免費取得配額。
`userRateLimitExceeded`	`usageLimits`	403	您已超過您在 Google Cloud Console 中設定的要求限制。此限制通常設為每日要求數、每 100 秒要求數、每位使用者每 100 秒要求數。建議您設定這項限制，以免單一或少數使用者耗盡每日配額，同時仍允許所有使用者存取合理的存取權。如要設定這些限制，請參閱限制 API 用量一節。
`notFound`	`geolocation`	404	要求有效，但沒有任何結果。
`parseError`	`global`	400	要求主體不是有效的 JSON。如需每個欄位的詳細資料，請參閱要求主體一節。

要求範例

如要使用範例資料試用 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
}

(如果您沒有 API 金鑰，請參閱「取得 API 金鑰」一文)。

如要進行額外測試，您可以透過 Places SDK for Android 和 Android Location API 收集 Android 裝置資訊，並使用 Places SDK for iOS 收集 iOS 裝置資訊。

常見問題

為什麼我的地理位置回應中，半徑為 accuracy 過大？

如果你的地理位置回應在 accuracy 欄位中顯示非常高的值，服務可能會根據要求 IP (而非 Wi-Fi 存取點或行動通信基地台) 進行地理位置定位。如果手機基地台或存取點並無有效或可辨識，就有可能發生這種情況。

如要確認問題，請在要求中將 considerIp 設為 false。如果回應是 404，請確認 wifiAccessPoints 和 cellTowers 物件無法設有地理位置。