您已全部設定完成!

若要開始開發,請參閱我們的開發人員文件

啟用 Google Maps Geolocation API

為協助您開始,我們將先引導您使用 Google Developers Console 來執行一些動作:

  1. 建立或選擇專案
  2. 啟用 Google Maps Geolocation API
  3. 建立適當的金鑰
繼續

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:行動裝置無線電類型。支援的值為 ltegsmcdmawcdma。雖然此欄位為選擇性,在有可用值的情況下便應該將它包括在內,以取得更準確的結果。
  • 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 AndroidAndroid Location API 從您的 Android 裝置收集資訊,或使用 Google Places API for iOS 從您的 iOS 裝置收集資訊。

常見問題

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

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

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

傳送您對下列選項的寶貴意見...

這個網頁
Google Maps Geolocation API
Google Maps Geolocation API
需要協助嗎?請前往我們的支援網頁