Listings APIListings API
登入

設定

設定 Listings API Python 用戶端：API 金鑰、基底 URL、逾時、重試和日誌記錄。

建構函式簽章

Python
listingsapi.ListingsAPI(    api_key: str | None = None,    *,    base_url: str | None = None,    timeout: float = 240.0,    max_retries: int = 2,)

所有引數皆為選用。若省略 api_key，用戶端會從環境變數讀取 LISTINGSAPI_KEY；若兩者皆未設定，則會在建構時拋出 AuthenticationError。

選項

選項型別預設值說明
api_keystr | NoneNoneAPI 金鑰。若未提供，則使用 LISTINGSAPI_KEY 環境變數。
base_urlstr | Nonehttps://listingsapi.comAPI 來源位址。結尾的斜線會自動移除。
timeoutfloat240.0每個請求的逾時時間，以秒為單位（個別套用至每個 HTTP 請求）。
max_retriesint2收到 429 和 5xx 回應時自動重試。設為 0 可停用。

API 金鑰

bash
export LISTINGSAPI_KEY="your-api-key"
Python
import listingsapi # From environment (recommended)client = listingsapi.ListingsAPI() # Explicit keyclient = listingsapi.ListingsAPI(api_key="your-api-key")

逾時

預設為 240.0 秒。對於執行時間短的指令碼或互動式使用情境，您可以設定較短的逾時時間：

Python
client = listingsapi.ListingsAPI(timeout=30.0)

逾時時間個別套用至每個 HTTP 請求。批次分頁呼叫（auto_paging_iter）中的每個請求都會獨立遵守此逾時設定。

重試

SDK 會在其 requests 工作階段上掛載 urllib3 Retry 配接器，針對 429、500、502、503 和 504 回應自動重試，但僅限安全方法：GET、HEAD 和 OPTIONS。寫入請求（POST、DELETE）只會傳送 1 次，失敗時會立即拋出錯誤。預設重試 2 次，指數退避係數為 0.5 秒。SDK 會遵守 Retry-After 標頭，因此，若 429 指定了等待時間，就會在等待該時間後重試。

v4 API 不支援 Idempotency-Key，也不會偵測重複寫入，因此逾時或傳回 5xx 的寫入操作可能已經提交。未經確認就重試，會建立第 2 個地點、貼文或評論回覆。再次執行寫入前，請先使用您掌握的索引鍵讀回該筆記錄。

Python
# More aggressive retry for long-running batch jobsclient = listingsapi.ListingsAPI(max_retries=5) # Disable retries entirely (e.g. when you want fast failures)client = listingsapi.ListingsAPI(max_retries=0)

若每次重試後仍收到 429，則會拋出 RateLimitError；手動實作退避的方式請參閱錯誤處理。

覆寫基底 URL

適用於預備環境或內部 Proxy：

Python
client = listingsapi.ListingsAPI(base_url="https://staging.example.com")

結尾的斜線會自動移除。所有請求都會使用此來源位址下的 /api/v4/ 路徑。

日誌記錄

SDK 透過標準 logging 模組，使用 listingsapi 日誌記錄器記錄日誌。在 DEBUG 層級下，會記錄每個請求的方法與 URL（以及 GET 的查詢參數）；絕不會記錄請求本文或您的 API 金鑰。

Python
import logginglogging.basicConfig()logging.getLogger("listingsapi").setLevel(logging.DEBUG) import listingsapiclient = listingsapi.ListingsAPI()client.locations.list(first=1)

後續步驟