Google Maps Geolocation API

總覽

Google Maps Geolocation API 能根據行動用戶端可偵測到的手機基地台和 Wi-Fi 節點相關資訊，傳回位置與精確半徑。本文件會說明將此資料傳送至伺服器，以及將回應傳回至用戶端所使用的通訊協定。

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

在您開始使用 Geolocation API 進行開發之前，請檢閱驗證需求 （您需要 API 金鑰）及 API 使用限制。

地理位置要求

地理位置要求是透過 POST 傳送到下列 URL：

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

您必須在要求中指定一個金鑰，將它以 key 參數之值的形式包括於要求中。key 是您應用程式的 API 金鑰。此金鑰會依配額管理目的識別您的應用程式。瞭解如何取得金鑰。

要求主體

要求主體必須是 JSON 格式。下列為支援的欄位，且所有欄位都是選擇性：

• homeMobileCountryCode：裝置之本網的行動裝置國家/地區代碼 (MCC)。
• homeMobileNetworkCode：裝置之本網的行動裝置網路代碼 (MNC)。
• radioType：行動裝置無線電類型。支援的值為 lte、gsm、cdma 與 wcdma。雖然此欄位為選擇性，在有可用值的情況下便應該將它包括在內，以取得更準確的結果。
• carrier：行動通訊業者名稱。
• considerIp：指定在無法使用 Wi-Fi 與手機基地台的情況下，是否要回復為 IP 地理位置。請注意，要求標頭的 IP 位址可能和裝置的 IP 不同。預設為 true。將 considerIp 設定為 false 以停用回復。
• cellTowers：手機基地台物件的陣列。請參閱下面的手機基地台物件一節。
• wifiAccessPoints：Wi-Fi 存取點物件的陣列。請參閱下面的 Wi-Fi 存取點物件一節。

{
  "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 陣列包含零個或更多手機基地台物件。

• cellId （必要）：蜂巢結構單元 (Cell) 的唯一識別碼。在 GSM 上，這是 Cell ID (CID)。CDMA 網路使用 Base Station ID (BID)。WCDMA 網路使用 UTRAN/GERAN Cell Identity (UC-Id)，這是一種結合 Radio Network Controller (RNC) 與 Cell ID 的 32 位元值。如果在 WCDMA 網路中只指定 16 位元的 Cell ID 值，可能會傳回不準確的結果。
• locationAreaCode （必要）：GSM 與 WCDMAnetworks 的 Location Area Code (LAC)。CDMA 網路的 Network ID (NID)。
• mobileCountryCode （必要）：手機基地台的行動裝置國家/地區代碼 (MCC)。
• mobileNetworkCode （必要）：手機基地台的行動裝置網路代碼。對於 GSM 與 WCDMA，這是 MNC；CDMA 使用 System ID (SID)。

下列選擇性欄位目前並沒有被使用，但在有可用值的情況下可以將它包括在內。

• age：從這個蜂巢結構單元 (Cell) 成為主要項目開始所經過的時間（以毫秒為單位）。如果 age 值是 0，則 cellId 代表目前的測量值。
• signalStrength：無線電訊號強度（以 dBm 為測量單位）。
• timingAdvance：提前時序值。

下列為 GSM 手機基地台物件的範例。

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

下列為 WCDMA 手機基地台物件的範例。

{
  "cellTowers": [
    {
      "cellId": 21532831,
      "locationAreaCode": 2862,
      "mobileCountryCode": 214,
      "mobileNetworkCode": 7
    }
  ]
}

Wi-Fi 存取點物件

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

• macAddress：(必要) Wi-Fi 節點的 MAC 位址。必須使用 : （冒號）做為分隔符號。
• signalStrength：目前的信號強度（以 dBm 為測量單位）。
• age：從這個存取點被偵測到開始所經過的時間（以毫秒為單位）。
• channel：用戶端用來與存取點通訊的頻道。
• signalToNoiseRatio：目前的信號雜訊比（以 dBm 為測量單位）。

下列為 Wi-Fi 存取點物件的範例。

{
  "macAddress": "00:25:9c:cf:1c:ac",
  "signalStrength": -43,
  "age": 0,
  "channel": 11,
  "signalToNoiseRatio": 0
}

地理位置回應

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

• location：使用者的預估緯度與經度，以度數為單位。包含一個 lat 及一個 lng 子欄位。
• accuracy：預估位置的準確度，以公尺為單位。這代表所指定 location 周圍的圓形半徑。

{
  "location": {
    "lat": 51.0,
    "lng": -0.1
  },
  "accuracy": 1200.4
}

錯誤

發生問題時，將會傳回標準格式錯誤回應內文，而且 HTTP 狀態碼將被設定為錯誤狀態。

回應包含具有單一 error 物件（而該物件具有下列金鑰）的物件：

• code：這和回應的 HTTP 狀態相同。
• message：錯誤的簡短描述。
• errors：已發生之錯誤的清單。每個錯誤都包含錯誤類型的識別碼 (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 金鑰對 Google Maps Geolocation API 而言無效。請確定您已包括整個金鑰，並已購買該 API 或啟用計費功能並啟用 API，以取得免費配額。
userRateLimitExceeded	usageLimits	403	您已超過您在 Google API Console 中設定的每位使用者每秒可以執行的要求數目限制。應該設定此限制以避免單一或小型群組的使用者耗盡您的每日配額，並同時針對所有使用者提供合理的存取權。
notFound	geolocation	404	要求有效，但未傳回任何結果。
parseError	global	400	要求主體不是有效的 JSON。請參考要求主體一節以取得每個欄位的詳細資料。

範例要求

如果要使用範例資料嘗試 Google Maps Geolocation API，請將下列的 JSON 儲存到檔案：

{
  "considerIp": "false",
  "wifiAccessPoints": [
    {
        "macAddress": "00:25:9c:cf:1c:ac",
        "signalStrength": -43,
        "signalToNoiseRatio": 0
    },
    {
        "macAddress": "00:25:9c:cf:1c:ad",
        "signalStrength": -55,
        "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": 33.3632256,
    "lng": -117.0874871
  },
  "accuracy": 20
}

（如果您沒有 API 金鑰，請參閱取得金鑰。）

針對其他測試，您可以使用 Google Places API for Android 和 Android Location API 從您的 Android 裝置收集資訊，或使用 Google Places API for iOS 從您的 iOS 裝置收集資訊。

常見問題

為什麼我一直在我的地理位置回應中取得非常大的 accuracy 半徑？

如果您的地理位置回應的 accuracy 欄位一直顯示非常高的數值，該服務可能是根據要求的 IP 來判斷地理位置，而不是使用 Wi-Fi 點或手機基地台。如果沒有有效或可辨識的手機基地台或存取點，會發生此情況。

如果要確認導致問題的是上述原因，請在您的要求中將 considerIp 設定為 false。如果回應是 404，便可以確認您的 wifiAccessPoints 與 cellTowers 物件無法進行地理位置判斷。