Listings APIListings API
サインイン

Python SDK

Listings APIの公式Pythonクライアントです。型付きリソース、カーソルページネーション、自動リトライ、名前付きエラーに対応しています。

listingsapi パッケージは、Listings API の公式 Python クライアントです。REST レイヤーをラップし、型付きのリソースクラス、カーソルベースのページネーション、一時的なエラー時の自動再試行、およびプラットフォームが HTTP 200 で返すエラーペイロードを含む各種の失敗に対応した名前付き例外を提供します。

インストール

bash
pip install listingsapi

Python 3.9 以降が必要です。実行時の依存関係は requests のみです。

認証

Python
import listingsapi # Reads LISTINGSAPI_KEY from the environment automaticallyclient = listingsapi.ListingsAPI() # Or pass the key explicitlyclient = listingsapi.ListingsAPI(api_key="your-api-key")

Listings API 開発者ダッシュボードの API Keys → New key から API キーを取得します。

クライアントは、省略可能なキーワード引数を 3 つ受け取ります。

オプションデフォルト値説明
base_urlhttps://listingsapi.comリクエストの送信先 API ホスト
timeout240.0リクエストごとのタイムアウト（秒）
max_retries2Retry-After に従った、429 および 5xx レスポンスに対する自動再試行

詳細は設定を参照してください。

簡単な使用例

list_locations.py
import listingsapi client = listingsapi.ListingsAPI() page = client.locations.list(first=5)for loc in page:  print(loc.name, loc.city) print(f"has_more: {page.has_more}")

リソース

各リソースはクライアントのプロパティとして提供されます。

プロパティ管理対象
client.locationsビジネス拠点：一覧取得、検索、1 回の呼び出しでの作成、更新、アーカイブ
client.reviewsレビューと返信、および client.reviews.analytics 配下の分析機能
client.postsGoogle と Facebook へのお知らせ、イベント、特典の投稿
client.socialSocialブランド、接続済みのソーシャルアカウント、および Facebook、Instagram、X、LinkedIn、Pinterest への投稿
client.listingsプレミアム掲載情報と音声掲載情報、重複、接続と接続解除
client.analyticsGoogle、Bing、Facebook のプロフィールのインサイト
client.photos拠点の写真：アップロード、削除、スターの付与
client.connected_accountsGoogle と Facebook への OAuth 接続
client.workflows構築済みの自動化機能：レビューへの自動返信、評判レポート、掲載情報の健全性監査

クライアント自体には、4 つの補助メソッドがあります。

Python
client.plan_sites()       # directories included in your planclient.subcategories()    # business categories (IDs for locations.add)client.countries()        # supported countries and states (ISO codes)client.subscriptions()    # active subscriptions for the account

ページネーション

一覧を返すメソッドは、カーソルベースのページネーションを使用します。ページネーションに対応する各メソッドは、反復可能で、.has_more、.next_page()、.auto_paging_iter()、.total を備えた SyncPage を返します。

Python
# Fetch one pagepage = client.locations.list(first=25)for loc in page:  print(loc.name) # Check if more pages existif page.has_more:  next_page = page.next_page() # Auto-paginate through every resultfor loc in client.locations.list(first=100).auto_paging_iter():  print(loc.name)

レスポンスオブジェクト

すべてのメソッドは、APIObject（属性アクセスと dict アクセスに対応）または SyncPage（反復可能でページネーションに対応）を返します。APIObject は .get() と .to_dict() にも対応しています。

Python
loc = client.locations.retrieve(16808) # Attribute accessprint(loc.name)print(loc.city) # Dict-style accessprint(loc["stateIso"]) # Safe access with a defaultprint(loc.get("website", "no website")) # Raw dictdata = loc.to_dict()

エラー処理

すべての SDK エラーは listingsapi.ListingsAPIError を継承しています。API で失敗すると、APIError、またはそのサブクラスである AuthenticationError、PermissionDeniedError、NotFoundError、ValidationError、RateLimitError（.retry_after を含みます）、InternalServerError のいずれかが送出されます。ネットワークで失敗すると、APIConnectionError が送出されます。

APIError は、status_code、code（最初のプラットフォームエラーコード、e.g。SY10005）、errors（各エントリは {"code", "message", "context"} の dict に正規化されます）、response_body を保持します。

プラットフォームは、一部の失敗を HTTP 200 の本文内で報告します。これには、トップレベルの errors[] ペイロード（無効なトークンに対しては SY90005 が返されます）と、success=false を含む書き込みレスポンスがあります。SDK はこれらに対しても例外を送出するため、success フラグを自分で確認する必要はありません。

Python
import listingsapi client = listingsapi.ListingsAPI() try:  client.locations.retrieve(999999)except listingsapi.NotFoundError:  print("No such location")except listingsapi.RateLimitError as e:  print(f"Rate limited, retry in {e.retry_after}s")except listingsapi.APIError as e:  print(e.status_code, e.code)  for err in e.errors:      print(err["code"], err["message"])

例外階層の全体については、エラー処理を参照してください。

次の手順