配額限制

為確保公平使用並維護系統穩定性，Google 商家檔案 (GBP) API 會對 API 要求強制執行配額。如果要求超出配額限制，API 會傳回 429 Too Many Requests HTTP 狀態碼 (或 gRPC 的 RESOURCE_EXHAUSTED)。

預設配額限制

下表列出 Google 商家檔案 API 的標準配額限制。限制分為以下兩類：

  • 每分鐘查詢次數 (QPM)：限制短期爆量流量，確保後端穩定性。
  • 每日查詢次數 (QPD)：管理平台整體的每日用量。
API 限制
Business Information API
  • 預設要求：每分鐘 300 次查詢
  • 建立地點要求：300 QPD
  • SearchGoogleLocation 要求：300 QPD
  • 更新位置要求：10000 QPD
  • 編輯：每個 Google 商家檔案每分鐘 10 次 (無法增加)
Account Management API 每分鐘 300 次查詢
Performance API 每分鐘 300 次查詢
Verifications API 每分鐘 300 次查詢
Lodging API 每分鐘 300 次查詢
Place Actions API 每分鐘 300 次查詢
Notifications API 每分鐘 300 次查詢

避免配額錯誤的最佳做法

在一天中持續且平均地發送要求，可避免絕大多數的配額錯誤。請按照下列最佳做法，確保應用程式能可靠地同步處理資料。

平均分配要求

請勿同時傳送大量要求，而是將要求分散在較長的時間內。舉例來說，每分鐘 300 次查詢的限制，相當於平均每秒 5 次要求。在要求之間加入短暫延遲，可避免流量突然暴增。

Traffic distribution patterns:

Spiky traffic (Discouraged): High burst of requests followed by an idle period
Requests |   |||                 |||
         |   |||                 |||
         +---------------------------------
           Time ──>

Even traffic (Recommended): Consistent rate of requests over time
Requests |  |  |  |  |  |  |  |  |  |
         |  |  |  |  |  |  |  |  |  |
         +---------------------------------
           Time ──>
 
import time

# Pace requests to stay within the 300 QPM limit (5 requests/sec)
for request in batch_requests:
    send_request(request)
    time.sleep(0.2)  # 200ms delay ensures a smooth distribution

實作指數輪詢和隨機延遲

收到 429 Too Many Requests 錯誤時，請使用指數輪詢搭配隨機延遲自動重試要求。這項標準做法包括等待一小段隨機時間後再重試，並逐步增加後續重試的延遲時間。

import random
import time
from googleapiclient.errors import HttpError

def call_api_with_retry(api_method, max_retries=5):
    base_delay = 1.0
    for attempt in range(max_retries):
        try:
            return api_method.execute()
        except HttpError as e:
            if e.resp.status == 429:
                if attempt == max_retries - 1:
                    raise e
                # Retry with exponential backoff and jitter
                sleep_time = random.uniform(0, base_delay * (2 ** attempt))
                time.sleep(sleep_time)
            else:
                raise e

最佳化資料存取

  • 快取靜態資料：將不常變更的資料儲存在本機，而非重複查詢 API。
  • 使用 Pub/Sub 通知：訂閱 Pub/Sub 通知，即可即時更新資料庫，不必輪詢 API。
  • 依序處理讀取量大的端點：避免對 SearchListings 等讀取量大的端點執行多個並行要求。請改用分頁符記依序處理工作。

申請提高配額

要求增加配額前，請先在 Google Cloud 控制台 中確認用量模式，確保要求量不會不必要地集中。

Google 商家檔案團隊會監控你的平均配額用量，確保你有效運用目前的限制。如果出現下列情況，配額提高要求通常會遭到拒絕：

  • 您的應用程式未持續達到目前的 QPM 上限。
  • 平均用量低於目前 QPM 上限的 50%。
  • 您的應用程式呈現高度尖峰的要求模式，而非平滑分布。

提交要求

如果您已採用這些最佳做法，但仍需要更多配額，請提交配額增加申請。

  1. 從下拉式選單中選取「Quota Increase Request」(配額增加要求)。
  2. 提供公司名稱、聯絡人電子郵件地址和專案編號。

提交表單後，Google 商家檔案團隊會審查您的要求，並決定是否適合增加配額。如果要求獲准，配額就會提高。如果要求遭拒，你會收到拒絕原因。