クイックスタート
Listings APIに接続し、拠点の一覧を取得し、1回の呼び出しで拠点を1つ作成し、レビューに返信します。
1. API キーを設定する
Listings API 開発者ダッシュボードの API Keys → New key からキーを取得します。SDK は LISTINGSAPI_KEY 環境変数からキーを自動的に読み取ります。
export LISTINGSAPI_KEY="your-api-key"2. 拠点の一覧を取得する
import listingsapi client = listingsapi.ListingsAPI() page = client.locations.list(first=5)for loc in page: print(loc.name, "--", loc.city, loc.stateIso) print(f"\nShowing {len(page)} locations, has_more={page.has_more}")python quickstart.py想定される出力:
Acme Dental Downtown -- New York NYAcme Dental Midtown -- New York NYAcme Dental Brooklyn -- Brooklyn NY Showing 3 locations, has_more=Falseすべてのページを自動的に取得するには、client.locations.list(first=100).auto_paging_iter() を使用します。カーソルをたどって各ページを取得するため、カーソルを手動で管理する必要はありません。
3. 1 回の呼び出しで拠点を作成する
locations.add() はすべての必須フィールドをキーワード引数として受け取り、ネットワーク呼び出しを行う前にクライアント側で検証します（名前の長さ、説明が 200 文字以上であること、カテゴリ、国、都市）。そのため、不正なペイロードは、明確な ValidationError とともに即座にエラーになります。
import listingsapi client = listingsapi.ListingsAPI() result = client.locations.add( name="Acme Dental Uptown", description=( "Acme Dental Uptown is a family-owned dental practice on the Upper " "West Side of New York offering preventive care, cosmetic dentistry, " "orthodontics, and emergency appointments. Our board-certified team " "combines modern equipment with a gentle, patient-first approach." ), sub_category_id=1432, country_iso="US", city="New York", street="482 Columbus Ave", state_iso="NY", postal_code="10024", phone="6443859313",) print(result.location.id)print(result.location.name)掲載先は説明を掲載情報の主要な本文として使用するため、API では 200 文字以上が必須です。有効な sub_category_id の値は client.subcategories() から取得します。
新しい ID は、TG9jYXRpb246MTY4MDg= のような base64 文字列として返されます。SDK が拠点 ID を受け取る箇所では、数値 ID と base64 ID のどちらも使用できるため、client.locations.retrieve(16808) と client.locations.retrieve("TG9jYXRpb246MTY4MDg=") は同じ拠点を取得します。
4. レビューに返信する
拠点のレビュー一覧を取得し、レビューの interactionId を使用して返信します。
import listingsapi client = listingsapi.ListingsAPI() reviews = client.reviews.list(16808, first=10, rating_filters=[4, 5])for review in reviews: print(review.rating, "-", review.get("content")) # A page can come back empty, and not every review is repliable: some sites# allow one owner reply per review, and some are read-only for the account.repliable = [r for r in reviews if r.get("canRespond")]if not repliable: print("nothing to reply to")else: client.reviews.respond( interaction_id=repliable[0].interactionId, content="Thank you for the kind review! We look forward to seeing you again soon.", )返信前に canRespond を確認し、ページが空でないことを必ず確認してからインデックスで要素にアクセスしてください。空のページに対して reviews[0] を実行すると IndexError が発生し、元のプラットフォームが受付を終了したレビューへの返信は、API ではなく掲載先で失敗します。
プラットフォームが返信を拒否すると、HTTP ステータスが 200 でも SDK は ValidationError を送出するため、success フラグを自分で確認する必要はありません。
5. エラーを処理する
import listingsapi try: client = listingsapi.ListingsAPI(api_key="bad-key") client.locations.list()except listingsapi.AuthenticationError as e: print("Invalid key:", e.code)キーが無効な場合、プラットフォームコード SY90005 を伴う HTTP 401 が返され、SDK は AuthenticationError を送出します。同じエラーコードが 200 の本文に含まれて返された場合も、SDK は防御的に処理します。例外の階層全体についてはエラー処理を、HTTP ステータスの対応表についてはエラーコードリファレンスを参照してください。