Listings APIListings API
サインイン

初めてのAPI呼び出し

認証を行い、拠点の一覧を取得し、レスポンスの構造を確認し、結果をページ単位で取得して、IDの仕組みを学びます。

このガイドは、はじめにの手順でアカウントとAPIキーを取得済みであることを前提としています。すべてのリクエストはhttps://listingsapi.comの本番APIに対して実行されるため、通常のAPIキーで書き込みを行うと、実際のデータが変更されます。実際の掲載先に影響を与えずにAPIを試すには、無料のサンドボックスデイパスを使用してください。

1. APIキーを設定する

ダッシュボードのAPIキーからキーをコピーし、シェルで一度exportしてください。

bash
export LISTINGSAPI_KEY="your-api-key"

キーにはアクセスレベルが設定されています。Read（読み取り）キーは、これらのガイドにあるすべての検索とレポートに使用できます。何かを作成または更新する場合、レビューに返信する場合、投稿を公開する場合は、Write（書き込み）キーが必要です。Readキーを書き込み用エンドポイントに送信すると、そのエンドポイントはエラーコードSY90016とともにHTTP 400を返します。

2. 拠点の一覧を取得する

他のエンドポイントではIDで拠点を参照するため、まず登録済みの拠点の一覧を取得します。RESTのAuthorizationヘッダーではAPIスキームを使用し、その後にスペースとAPIキーを続けます：Authorization: API <YOUR_API_KEY>。

List locations
curl "https://listingsapi.com/api/v4/locations?first=5" \-H "Authorization: API $LISTINGSAPI_KEY"

3. レスポンスを読み取る

REST APIは、配列だけではなく、入れ子構造のレスポンスを返します。操作名はdataの下にあり、一覧の結果はedgesのコネクションとして返され、各エッジにはnodeが含まれます。

JSON
{  "data": {    "allLocations": {      "edges": [        {          "cursor": "TG9jYXRpb246MTgwMDI4OQ==",          "node": {            "id": "TG9jYXRpb246MTgwMDI4OQ==",            "databaseId": 1800289,            "name": "Jenny Home",            "city": "Austin",            "stateIso": "TX",            "approved": "APPROVED",            "subCategoryName": "Restaurants"          }        }      ],      "pageInfo": {        "hasNextPage": false,        "endCursor": "TG9jYXRpb246MTgwMDI4OQ=="      }    }  }}

Python SDKは、オブジェクトを格納した反復処理可能なページを返します。Node SDKはlocationsとpageInfoを返します。REST APIを直接呼び出す場合は、data.allLocations.edges[].nodeを読み取ってください。

4. 結果をページごとに取得する

拠点とレビューの一覧取得用エンドポイントは、カーソルによるページネーションを使用します。firstでページをリクエストし、次にpageInfo.endCursorをafterとして渡して次のページを取得します。SDKでは、すべてのページを自動的に読み取れます。

Next page
curl "https://listingsapi.com/api/v4/locations?first=50&after=TG9jYXRpb246MTgwMDI4OQ==" \-H "Authorization: API $LISTINGSAPI_KEY"

すべてのエンドポイントがこのページネーション方式を使用するわけではありません。接続済みアカウント、重複の集計、投稿では、pageとperPage、およびrecords配列を使用します。各ガイドには、そのエンドポイントが使用するページネーション形式を記載しています。

5. 2種類のID

すべてのレコードには2つの識別子があります。idはTG9jYXRpb246MTgwMDI4OQ==のようなbase64文字列で、デコードするとLocation:1800289になります。databaseIdは、エンコードされていない数値の1800289です。

base64形式のidを保存してください。すべての書き込み用エンドポイントではbase64でエンコードされたIDが必要であり、Webhookペイロードでもこの形式の値が返されます。パスで拠点を指定する読み取り用エンドポイントの多くは、エンコードされていない数値も受け付け、どちらのSDKも両方の形式を受け付けて必要なエンコードを行います。

6. エラーとレート制限

失敗時のレスポンスでは、対応するHTTPステータスとerrors配列が返されます。メッセージの先頭には、エラーコードに記載されているSYエラーコードが付いています。

JSON
{  "data": { "allLocations": null },  "errors": [{ "message": "SY90005: Invalid Token" }]}

レート制限はプランごとに設定され、リクエスト数は1分、1時間、1日単位で集計されます。Launchでは、1分あたり10リクエストが許可されます。制限を超えると、APIはRetry-Afterヘッダーとともに429を返すため、すぐに再試行せず、そのヘッダーが示す秒数だけ待ってください。SDKはRateLimitErrorを送出し、同じ値を取得できるようにします。詳細はレート制限を参照してください。

次の手順