Google Maps APIs Web 服務使用限制

本頁面僅適用於舊版 Maps APIs for Work 或 Maps API for Business 授權的客戶。本頁面不適用於 2016 年 1 月推出之新版 Google Maps APIs Premium Plan 的客戶。

2011 年 12 月

Google Maps APIs Web 服務的使用受到每 24 小時期間要求量的明確限制規範。傳送超過此限制的要求會收到錯誤訊息。

使用限制記錄於 Google Maps APIs for Work 舊版授權的常見問題中。

本文適用於達到這些限制,而可能需要最佳化應用程式來更有效率地使用 Web 服務的 Google Maps APIs for Work 客戶。

基本概念

Google Maps 提供 Web 服務做為介面,用來要求 Google 地圖資料以便在您的應用程式中使用。這些服務只能與 Google 地圖一起使用;禁止只使用這些服務的資料卻不在 Google 地圖上顯示它們。如需完整詳細資料,請參閱 Google Maps APIs 服務條款授權限制

限制 Google Maps APIs Web 服務使用量的配額有兩種:長期(每日配額)與短期(要求速率配額)。如果您超出使用限制或以其他方式濫用服務,Web 服務將會傳回特定錯誤訊息。如果您繼續超出限制的用量,系統可能會封鎖您對 Web 服務的存取權。也可能收到 403 禁止回應。

請注意:用戶端 API 有不同限制。Maps JavaScript API 針對每個地圖工作階段設有速率限制,以使要求可以於使用者之間分配。這使瀏覽器型用量可以隨著您的使用者人數提升而調整。如需有關如何選擇伺服器端 Web 服務與用戶端 Web 服務的資訊,請參閱地理編碼策略文件。

問題

下列情況將會超出 Google Maps APIs Web 服務使用限制:

  • 每天傳送太多要求。
  • 傳送要求的速度太快,換句話說,便是每秒傳送太多要求。
  • 長時間以過快的速度傳送要求,或是濫用 Web 服務。
  • 超過其他使用限制;例如 Google Maps Elevation API 中每個要求的點。

超出使用限制

如果您超出使用限制,便會收到 OVER_QUERY_LIMIT 狀態碼做為回應。

這表示 Web 服務將會停止提供標準回應,並切換為只傳回 OVER_QUERY_LIMIT 狀態碼,直到有更多用量可以使用。這可能會在下列情況發生:

  • 如果該錯誤是因為您的應用程式每秒傳送太多要求而產生,便會在幾秒之內發生。
  • 如果該錯誤是因為您的應用程式每天傳送太多要求而產生,便會在接下來的 24 小時內發生。每日配額將在太平洋時間的午夜重設。

此螢幕側錄提供適當的要求節流與錯誤處理的逐步說明,且適用於所有 Web 服務。

在收到有狀態碼 OVER_QUERY_LIMIT 的回應時,您的應用程式應判斷哪一個使用限制已超過。透過暫停 2 秒鐘並重新傳送相同要求,即可做到這件事。如果狀態碼依舊是 OVER_QUERY_LIMIT,則表示您的應用程式每天傳送的要求太多。不然就是您的應用程式每秒傳送的要求太多。

此處是 Python 中的範例實作:

url = "MAPS_API_WEBSERVICE_URL"
attempts = 0
success = False

while success != True and attempts < 3:
  raw_result = urllib.urlopen(url).read()
  attempts += 1
  # The GetStatus function parses the answer and returns the status code
  # This function is out of the scope of this example (you can use a SDK).
  status = GetStatus(raw_result)
  if status == "OVER_QUERY_LIMIT":
    time.sleep(2)
    # retry
    continue
  success = True

if attempts == 3:
  # send an alert as this means that the daily limit has been reached
  print "Daily limit has been reached"

注意:也有可能收到 OVER_QUERY_LIMIT 錯誤:

應用程式應在傳送要求之前確認未達到這些限制。

HTTP 403 回應

向 Web 服務發出的要求也可能收到 HTTP 403 (禁止)錯誤。在大多數情況下,這是因為網址簽章無效所導致。若要確認這件事,請移除 clientsignature 參數並再試一次:

  • 如果回應為 HTTP 200 (OK),則表示簽章是問題所在。
    這與使用限制無關;如需詳細資料,請參閱 Google Maps APIs for Work 文件的 Web 服務一章中的疑難排解驗證問題
  • 如果回應仍是 HTTP 403 (禁止)錯誤,表示簽章不一定是問題所在,反而可能與使用限制有關。
    這通常表示您對 Web 服務的存取已遭封鎖,原因是您的應用程式已超過使用限制太久,或以其他方式濫用 Web 服務。如果碰到此問題,請存取 Google Cloud Support Portal。聯絡資訊也可於支援與資源頁面取得。

向所有 Web 服務提出的要求都需要網址簽章。如果要求包含 client 參數,卻遺失 signature 參數(反之亦然),則要求也會遭到拒絕,並收到 HTTP 403 (禁止)錯誤。

解決方案

上述問題可以透過結合兩種方式來解決:

  1. 最佳化應用程式來更有效率地使用 Web 服務,藉此降低使用量。
  2. 如果可能,為您的 Google Maps APIs for Work 授權購買額外額度,藉以增加使用限制。

本文會著重於最佳化應用程式以更有效率地使用 Web 服務的方式。

健全狀態檢查

在進入如何更有效率地使用 Web 服務的詳細資料之前,花些時間檢查所使用的服務與授權是否正確是值得的。

驗證您的使用案例

對於沒有使用者即時輸入或無法使用網頁瀏覽器的應用程式,最適合使用 Google Maps APIs Web 服務。這通常發生在您取得與使用者輸入無關的資料集時。例如,您有一個需要地理編碼的固定地址資料集,譬如在房地產網站上供銷售的一組不動產,或一組商店位置。

當使用 Google Maps APIs Web 服務時,所有要求都會計入您用戶端編號的(每日及每秒)配額中。此配額對每個用戶端編號都是整體的,不論用來傳送要求的 IP 位址有多少。

在瀏覽器中使用用戶端 Maps JavaScript API 服務設有每個地圖工作階段的速率限制。這表示要求會分散到您所有的使用者上,而且隨著使用者數量增長而增加。因此,只要有可能,最好一律使用用戶端 API。如果您從使用者收集地址且需要即時進行地理編碼,例如執行使用者住家地址附近的商店搜尋,那麼用戶端 API 是最佳搭配。

如需有關此主題更詳細的討論,請參閱地理編碼策略文件。雖然此文件是針對地理編碼,但其中的建議可套用至所有 Web 服務,說明何時應使用伺服器端 Web 服務,以及何時應使用其用戶端 Web 服務。

使用 Google Maps APIs for Work 授權

如果您有 Google Maps APIs for Work 授權,請確認您的要求正確包含您的用戶端編號。

Google Maps APIs for Work 客戶比免費 API 使用者獲得更高的 Google Maps APIs Web 服務使用限制。為了獲得這個好處,您的應用程式必須正確設定 client 參數,如本指南 Web 服務一章中所述。

無法正確使用 Google Maps APIs for Work 用戶端編號的應用程式將不被視為企業,無法獲得僅限企業的功能與配額,不受 Google Maps APIs for Work 穩健的服務水準協議保障,無權獲得技術支援,也不受一般 Google Maps APIs 服務條款授權限制規範。

如何最佳化

更有效率地使用 Web 服務可以概括為兩大主要目標:藉著僅在真正必要時傳送要求來降低使用量,以及平均分散使用量使其低於限制。

快取結果

Google Maps APIs 服務條款第 10.5.d 節規定,您只能基於網路延遲而改善 Google Maps APIs 實作效能的目的(但不是為了防止 Google 準確追蹤使用量的目的),而且只有在此類儲存空間是:暫存(且在任何情況下皆不得超過 30 個日曆天數);安全;不操作或彙總任何部分的內容或服務;以及不以任何方式修改資料引用標示的情況下,才能儲存有限量的內容。

這表示您可以暫時快取 Web 服務回應,以避免在短時間內傳送重複要求。從 Web 服務的回應一律包括 Cache-Control HTTP 標頭,以表示該結果可供快取多久,目前為 24 小時:

Cache-Control: public, max-age=86400

此標頭應該要遵守。快取的實作,可以使用 Web Proxy(應該可立即使用此功能),也可以使用您自己的實作。值得一提的是,部分 HTTP 用戶端程式庫也會快取 HTTP 回應。

若要提高在快取中找到所需資料的機率,LatLng 座標應該透過四捨五入到小數點後 6 位數來標準化,這可在赤道附近提供約 11 公分的精準度。增加更多小數點並不會影響來自 Web 服務的結果,但是卻會降低在快取中找到所需資料的機率。

對要求進行節流處理

應用程式應該對要求進行節流處理,以避免超過使用限制,請記住,這些適用於每個用戶端編號,不論用來傳送要求的 IP 位址有多少。

您可以透過將要求放進佇列,並追蹤要求傳送到何處,藉以進行節流處理。由於速率限制為 10 QPS(每秒查詢數),因此在傳送第 11 個要求時,您的應用程式應該檢查第一個要求的時間戳記,並等候 1 秒鐘的時間。相同做法應該套用到每日限制上。

即使正確實作節流處理,應用程式仍應留意有狀態碼 OVER_QUERY_LIMIT 的回應。如果收到此類回應,請使用上文超出使用限制一節中說明的「暫停並重試」機制來偵測哪一個限制已超過。

處理積存

只要正確實作節流處理,對 Web 服務傳送的要求將不會超過使用限制。不過,應用程式可能會收到比 Web 服務使用限制允許的更大量輸入,或以更高的速度收到。這可能導致節流處理的佇列顯著成長,造成待處理要求的積存。

在處理大量積存時,您的應用程式可能會達到每日使用限制。如果針對每日限制正確實作節流處理,應用程式應該會停止傳送要求;否則傳送額外要求將會收到有狀態碼 OVER_QUERY_LIMIT 的回應。在這兩種情況下,積存並不會減少。

如果整天或整週的平均要求量未達使用限制,您的應用程式應該能在較低輸入流量期間疏解積存。否則,您可能必須為您的 Google Maps APIs for Work 授權增加每日額度(請參閱下一節)。

如果最佳化不足以解決問題

如果您已實作了上述最佳化,但您的要求積存仍越來越多,無論是以每日為準或一天中的所有時間,您可能真的必須增加您 Google Maps APIs for Work 授權的每日或每秒使用限制。在此情況下,請聯絡您的 Google Maps APIs for Work 客戶經理,討論可用的選項。