地理位置要求與回應

地理位置要求

地理位置要求會使用 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 (預設)、cdma wcdmalte已拒絕 的時間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,對其他值來說是選用項目。
使用 gsmcdmawcdmalte:0–65535。
有效範圍,設有 nr:0–16777215。
mobileCountryCode number (uint32) 基地台的行動裝置國家/地區代碼 (MCC)。 對於 radioType gsm (預設)、wcdma ltenr;未用於 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 位元無線電網路控制器識別碼 (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,
    }
  ]
}

WiFi 存取點物件

要求主體的 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 位址。

舉例來說,您可以從 名為 macsmacAddress 字串陣列:

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
}