在地理編碼時最佳化配額用量

地理編碼是指將地址 (例如 1600 Amphitheatre Parkway, Mountain View, CA) 轉換成地理座標 (例如 37.423021, -122.083739) 的程序，您可以透過這項程序放置標記或在地圖上定位。Google Maps Platform API 提供兩種地理編碼方法：

  • 用戶端地理編碼：在瀏覽器中執行，通常是為了回應使用者動作。Maps JavaScript API 提供可為您提出要求的類別。如要瞭解這種做法，請參閱 Maps JavaScript API 說明文件。
  • HTTP 伺服器端地理編碼：可讓伺服器直接向 Google 伺服器查詢地理編碼。Geocoding API 是提供這項功能的網路服務。通常，您會將這項服務與在伺服器端執行的其他程式碼整合。如需伺服器端地理編碼的說明，請參閱 Geocoding API 說明文件。

用戶端和伺服器端地理編碼範例

以下是用戶端地理編碼範例，可擷取地址、進行地理編碼、將地圖中心移至該位置，並在該處新增地圖標記：

geocoder = new google.maps.Geocoder();
geocoder.geocode({ 'address': address }, function(results, status) {
  if (status == google.maps.GeocoderStatus.OK) {
    map.setCenter(results[0].geometry.location);
    var marker = new google.maps.Marker({
      map: map,
      position: results[0].geometry.location
    });
  }
});

如需更多範例，請參閱 Maps JavaScript API 說明文件。

以下範例說明如何使用 Python，在 Geocoding API v4 中提出伺服器端地理編碼要求：

import json
import urllib.request

address = "1600+Amphitheatre+Parkway,+Mountain+View,+CA"
key = "my-key-here"
url = f"https://geocode.googleapis.com/v4/geocode/address/{address}"
headers = {"X-Goog-Api-Key": key}

req = urllib.request.Request(url, headers=headers)
with urllib.request.urlopen(req) as response:
    result = json.loads(response.read().decode("utf-8"))

這會產生包含下列內容的 JSON 物件：

{
  "results": [
    {
      "place": "places/ChIJiSSC8QK6j4AR98Thup8mqTc",
      "placeId": "ChIJiSSC8QK6j4AR98Thup8mqTc",
      "location": {
        "latitude": 37.4224864,
        "longitude": -122.0855962
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.4211700197085,
          "longitude": -122.08691558029149
        },
        "high": {
          "latitude": 37.4238679802915,
          "longitude": -122.08421761970851
        }
      },
      "bounds": {
        "low": {
          "latitude": 37.4221145,
          "longitude": -122.0860002
        },
        "high": {
          "latitude": 37.4228775,
          "longitude": -122.085133
        }
      },
      "formattedAddress": "Google Building 41, 1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "postalAddress": {
        "regionCode": "US",
        "languageCode": "en",
        "postalCode": "94043-1351",
        "administrativeArea": "CA",
        "locality": "Mountain View",
        "addressLines": [
          "1600 Amphitheatre Pkwy"
        ]
      },
      "addressComponents": [
        {
          "longText": "Google Building 41",
          "shortText": "Google Building 41",
          "types": [
            "premise"
          ],
          "languageCode": "en"
        },
        {
          "longText": "1600",
          "shortText": "1600",
          "types": [
            "street_number"
          ]
        },
        {
          "longText": "Amphitheatre Parkway",
          "shortText": "Amphitheatre Pkwy",
          "types": [
            "route"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Mountain View",
          "shortText": "Mountain View",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Santa Clara County",
          "shortText": "Santa Clara County",
          "types": [
            "administrative_area_level_2",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "California",
          "shortText": "CA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "United States",
          "shortText": "US",
          "types": [
            "country",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "94043",
          "shortText": "94043",
          "types": [
            "postal_code"
          ]
        },
        {
          "longText": "1351",
          "shortText": "1351",
          "types": [
            "postal_code_suffix"
          ]
        }
      ],
      "types": [
        "premise",
        "street_address"
      ]
    }
  ]
}

如需更多範例，請參閱 Geocoding API v4 總覽和地址地理編碼指南。

配額和費用注意事項

本文件概述的策略，是根據地理編碼成本、配額和頻率限制制定。

費用

每日配額 (QPD) 限制不適用於地理編碼要求。相反地，無論是透過瀏覽器在用戶端進行，還是透過 Geocoding API 網路服務在伺服器端進行，每項地理編碼要求都會按要求計費。如要管理使用成本，建議您管理用量限制和配額。

頻率限制

地理編碼服務的頻率限制為每分鐘 3,000 次查詢 (QPM)，計算方式為用戶端和伺服器端查詢的總和。

如果定期執行用戶端地理編碼要求 (例如在行動應用程式中)，當所有使用者同時提出要求 (例如每分鐘的同一秒)，要求可能會傳回錯誤。如要避免這種情況，請考慮下列任一做法：

  • 在要求中加入隨機間隔 (抖動)。請確保要求是隨機向全體使用者族群發出。
  • 如果是開發 Android 應用程式，請使用非精準重複鬧鐘。
  • 如果是開發 Android 應用程式，請選取適當的位置策略。

快取

請參閱 Geocoding API 政策，瞭解快取相關規定。

v4 的伺服器端與用戶端架構

Geocoding API v4 (包括 SearchDestinations、GeocodeAddress、GeocodeLocation 和 GeocodePlace) 是伺服器對伺服器 API。從後端伺服器呼叫第 4 版端點有以下重要優勢：

  • 超地方抵達智慧功能：SearchDestinations 方法 (POST /v4/geocode/destinations) 只能透過伺服器端 REST 或 gRPC 要求使用，並會傳回建築物入口、可規劃路線的導航點、建築物輪廓和附近地標，這些資訊在用戶端瀏覽器地理編碼器中無法取得。
  • 強化 API 安全性：伺服器端呼叫可保護 API 金鑰和 OAuth 權杖，避免在用戶端瀏覽器中曝光。請參閱「API 安全性」。
  • 回應欄位遮罩：伺服器端第 4 版端點支援欄位遮罩，可讓您只要求應用程式所需的欄位，盡可能縮減酬載大小和延遲時間。

用戶端瀏覽器查詢的使用時機

如果是回應即時按鍵輸入的互動式瀏覽器應用程式，建議將用戶端 Place Autocomplete (用於釐清使用者輸入內容並取得地點 ID) 與後端呼叫 SearchDestinations 或 GeocodePlace 結合，安全擷取超地方詳細資料或座標。