總覽

引言

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 類型 說明 附註
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 陣列包含零個或多個儲存格塔物件。

欄位 JSON 類型 說明 附註
cellId number (uint32) 儲存格的專屬 ID。 對於 radioType gsm (預設)、cdmawcdmalte 而言,此為必填屬性;針對 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,此為必填屬性。
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 Cell Identity (ECI),是包含 20 位元 E-UTRAN 節點 B ID (eNBId) 和 8 位元儲存格 ID (CID) 的 28 位元整數值。
    公式:enb_id << 8 | cid
    有效範圍:0 至 268435455。
    注意:如果在 LTE 網路中僅指定 8 位元儲存格 ID 的值,會導致錯誤或零的結果。

在 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。

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

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

WiFi 存取點物件

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

欄位 JSON 類型 說明 附註
macAddress string Wi-Fi 節點的 MAC 位址。這通常稱為 BSS、BSSID 或 MAC 位址。 必填。: (冒號) 是十六進位字串。
signalStrength number (double) 目前的訊號強度 (單位為 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": "84:d4:7e:f6:99:64",
      "signalStrength": -54,
      "signalToNoiseRatio": 0
    },
    {
      "macAddress": "84:d4:7e:f6:99:71",
      "signalStrength": -43,
      "signalToNoiseRatio": 0
    },
    {
      "macAddress": "84:d4:7e:f7:21:35",
      "signalStrength": -32,
      "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.4237423,
      "lng": -122.0915814
  },
  "accuracy": 20
}

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

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

常見問題

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

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

如要確認問題,請在要求中將 considerIp 設為 false。如果回應是 404,即表示您確認 wifiAccessPointscellTowers 物件無法用於地理位置。