連携方法を選ぶ

アプリケーションのアーキテクチャと連携要件に基づいて、REST API、Python SDKとNode SDK、MCPサーバー、Webhookを比較します。

すべての連携方法で、同じAPIキーとベースURL（https://listingsapi.com/api/v4）を使用します。APIリクエストにはREST APIまたはSDK、イベントに基づく更新にはWebhook、AIエージェントの支援による連携にはMCPサーバーを使用できます。

1. APIの呼び出し方法を選ぶ

REST API。 REST APIを使用すると、HTTP経由ですべてのエンドポイントに直接アクセスできます。アプリケーション側でレスポンスを解析し、両方のページネーション方式に対応し、errors[]配列を調べてAPIエラーを確認する必要があります。

Python SDK。 pip install listingsapiでPython SDKをインストールします。このSDKは、client.locationsやclient.reviewsなどのインターフェースを通じてリソースクラスを提供します。auto_paging_iter()でカーソルページネーションを処理し、429または5xxのレスポンスが返されたリクエストを再試行し、APIリクエストを送信する前にlocations.add()で拠点のペイロードを検証します。Python SDKを参照してください。

Node SDK。 npm install listingsapi-jsでNode SDKをインストールします。Node.js 18以降が必要で、TypeScriptの型定義が含まれており、実行時の依存関係はありません。SDKのメソッドは、client.fetchAllLocations()のようにクライアントインスタンスから直接呼び出せます。fetchAll: trueを設定すると、ページ分割されたすべての結果を1つのレスポンスで取得できます。数値IDは、APIリクエストが送信される前に自動的にBase64エンコードされます。Node SDKを参照してください。

MCPサーバー。 Streamable HTTPを使用して、Claude、ChatGPT、Cursor、GeminiなどのAIクライアントをhttps://listingsapi.com/mcpのListingsAPI MCPサーバーに接続します。ローカルにMCPサーバーをインストールする必要はありません。このサーバーは、ListingsAPIのドキュメントの検索、RESTエンドポイントの探索、サポートされているAPI操作の実行に使用するツールを公開しています。認証にはAPIキーまたはOAuthを使用します。/dashboard/mcpを開くと、クライアントの設定、利用可能なMCPツール、各ツールに必要なAPIキーの権限レベルを確認できます。詳しくはMCPでAIエージェントを接続するを参照してください。

Webhook。 REST API、SDK、またはMCPサーバーとともにWebhookを使用すると、イベントに基づく更新を受信できます。拠点、掲載情報、レビュー、または投稿に変更があると、ListingsAPIはアカウントに設定されたWebhook URLにHTTP POSTリクエストを送信します。これにより、アプリケーションは更新を確認するためにAPIをポーリングすることなく、変更を処理できます。Webhookの概要を参照してください。

2. 認証モデルを理解する

REST APIとSDKは、APIキーを使用してリクエストを認証します。API認証スキームを使用して、HTTPリクエストのAuthorizationヘッダーにキーを渡します。

Authorization: API <YOUR_API_KEY>

APIキーには、Read（読み取り）またはWrite（書き込み）のいずれかのアクセス権があります。Readキーでは、検索やレポートを含む読み取り操作にアクセスできます。リソースを作成または更新する操作には、Writeキーが必要です。書き込み用エンドポイントにReadキーを送信すると、HTTP 400とエラーコードSY90016が返されます。

APIキーのスコープは1つのアカウントに限定されます。同じアカウントのキーで行われたリクエストは、同じアカウント単位のレート制限枠を消費します。

MCPサーバーはOAuth認証にも対応しています。MCPクライアントは、APIキーを提供する代わりに、OAuthを使用してブラウザー経由で認証できます。REST APIとSDKのリクエストは、Authorizationヘッダーを使用して認証します。設定の詳細については、認証のドキュメントを参照してください。

3. ページネーションモデルを理解する

RESTの一覧取得エンドポイントでは、カーソルベースまたはオフセットベースのページネーションを使用します。SDKはこれらのページネーションモデルを抽象化します。

カーソルベースのエンドポイントは、firstとafterを受け付けます。結果はedges[].nodeで返され、pageInfo.endCursorには次のリクエスト用のカーソルが含まれます。

オフセットベースのエンドポイントは、pageとperPageを受け付けます。結果はrecords[]に格納されて返され、pageInfo.totalRecordsは取得可能なレコードの総数を示します。

以下の例では、3つの連携方法を使用して、同じ拠点一覧取得操作を実行します。cURLによる実装では、アプリケーションがAPIレスポンスの構造を直接解析する必要があります。

curl "https://listingsapi.com/api/v4/locations?first=5" \-H "Authorization: API $LISTINGSAPI_KEY" # Read data.allLocations.edges[].node, then pass# data.allLocations.pageInfo.endCursor back as ?after= for the next page.

すべての連携方法で、APIエラーはerrors[]配列に格納されて返され、各エラーメッセージの先頭にはSYエラーコードが付きます。書き込みリクエストでは、success: falseを伴うHTTP 200が返される場合があるため、操作が成功したと判断する前にレスポンスボディを確認する必要があります。

アカウントがレート制限を超えると、APIはRetry-Afterヘッダーを含むHTTP 429を返します。Launchプランでは、1分あたり最大10件のリクエストが可能です。詳細については、エラーコードとレート制限のドキュメントを参照してください。

4. Webhookとポーリングのどちらを使うか選ぶ

全拠点の夜間同期など、決まったスケジュールでアプリケーションがリソースの状態を取得する必要がある場合や、必要なイベントがWebhookに対応していない場合は、ポーリングを使用します。新しいレビューの受信、掲載情報のステータス変更、Google投稿の却下など、変更の発生時にアプリケーションで処理する必要がある場合は、Webhookを使用します。

/dashboard/webhooksで、アカウントごとに1つのWebhook URLを設定します。各Webhookリクエストには、次の形式のX-ListingsAPI-Signatureヘッダーが含まれます。

X-ListingsAPI-Signature: sha256=<base64 HMAC>

Webhookエンドポイントは、5秒以内に2xxレスポンスを返す必要があります。配信に失敗しても再試行は行われません。

Webhookイベントをトリガーとして、APIからリソースの現在の状態を取得します。Webhookの配信は再試行されないため、取りこぼした可能性のある更新を検出する照合処理を定期的に実行してください。実装例については、Webhookでイベントに対応するを参照してください。

5. 一覧で比較する

次の手順

• 拠点を追加する：選択した方法で、初めての書き込み呼び出しを行います。
• Webhookでイベントに対応する：署名付きリクエストを受信する仕組みを構築します。
• Python SDKとNode SDK：インストールと設定を行い、メソッド一覧を確認します。
• 認証、レート制限、エラーコード：すべての方法に共通する3つのリファレンスです。