地理位置要求與回應

地理位置要求

地理位置要求會使用 POST 傳送至下列網址：

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

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

要求主體

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

以下是 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 陣列含有零個或多個行動通信基地台物件。

以下為不使用的選填欄位，如果可以使用值，則可加入此欄位。

正在計算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 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。

以下是 NR 基地台物件的範例。

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

Wi-Fi 存取點物件

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

以下是 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 等緩解措施。這個做法可以在應用程式需要位置估算的需求，以及其精確度和喚回度要求之間權衡取捨。下列篩選技術示範如何篩選輸入內容，但不要顯示身為應用程式工程師選擇套用的緩解措施。

本機管理的 MAC 位址對 API 來說不是實用的位置信號，因此會不發出通知，從要求中捨棄。如要移除這類 MAC 位址，請確保 macAddress 中最重要位元組的第二個最低位元是 0 (例如 02:00:00:00:00:00 中 2 所代表的 1 位元)。廣播 MAC 位址 (FF:FF:FF:FF:FF:FF) 是這個篩選器實際上會排除的 MAC 位址範例。

00:00:5E:00:00:00 和 00:00:5E:FF:FF:FF 之間的 MAC 位址範圍會保留給 IANA，且通常用於網路管理和多點傳送功能，因此這些位址將不會做為位置信號使用。您也應從輸入內容中移除這些 MAC 位址。

舉例來說，您可以從名為 macs 的 macAddress 字串陣列收集地理位置的可用 MAC 位址：

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")));
    

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')]
    

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
}