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_retriesint2429および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秒です。Retry-Afterヘッダーに従うため、429に待機時間が指定されている場合は、その時間だけ待機してからリトライします。

v4 APIはIdempotency-Keyをサポートせず、書き込みの繰り返しも検出しないため、タイムアウトした書き込みや5xxを返した書き込みでも、すでにコミットされている可能性があります。確認せずにリトライすると、拠点、投稿、またはレビューへの返信が重複して作成されます。書き込みを繰り返す前に、自分で管理しているキーを使ってレコードを再取得してください。

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の上書き

ステージング環境や内部プロキシで役立ちます。

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)

次の手順