Listings APIListings API
サインイン

はじめに

アカウントを作成し、支払い方法を追加してAPIキーを取得し、Listings APIを初めて呼び出します。

このガイドでは、アカウントの作成、最初のAPIキーの取得、Listings APIへのリクエストの送信方法を説明します。

1. アカウントを作成する

料金ページでプランを選択して登録フォームを開き、名、姓、仕事用のメールアドレス、会社名を入力します。すでにアカウントをお持ちの場合は、サインインしてください。

2. 支払い方法を追加する

フォームを送信すると、カードを追加するために決済サービスのページへ移動します。無料トライアルはすぐに開始され、トライアル終了時に選択したプランへ移行するため、課金を希望しない場合は終了前にキャンセルしてください。現在のトライアル期間とプランの上限については、料金に関するFAQをご覧ください。

3. パスワードを設定してサインインする

決済手続きが完了すると、パスワードを設定してアカウントを有効化するためのリンクをメールでお送りします。パスワードの設定後、メールアドレスとパスワードでサインインするか、代わりにEmail me a sign-in link（サインインリンクをメールで受け取る）を選択して、1回限り有効なマジックリンクを受け取ります。

4. APIキーを取得する

最初のAPIキーはアカウントの作成時に自動で発行され、ダッシュボードのAPI Keysで確認できます。別のキーを作成するには、New key（新しいキー）を選択し、名前を付けてアクセスレベル（Read（読み取り）またはWrite（書き込み））を選択します。

5. 最初のリクエストを送信する

すべてのリクエストはAuthorizationヘッダーで認証します。値は、文字列API （末尾のスペースに注意）の後にキーを続けたものです。

Shell
curl https://listingsapi.com/api/v4/locations \  -H "Authorization: API $LISTINGSAPI_KEY"

レスポンスは単独の配列ではなくネストされた構造になっており、結果はdata.allLocationsの下にあり、各レコードはedges[].nodeです。pageInfoにはページネーションのカーソルと合計件数が入ります。

JSON
{  "data": {    "allLocations": {      "edges": [        {          "cursor": "TG9jYXRpb246MTgwMDI4OQ==",          "node": {            "id": "TG9jYXRpb246MTgwMDI4OQ==",            "databaseId": 1800289,            "name": "Jenny Home",            "city": "Austin",            "stateIso": "TX",            "countryIso": "US"          }        }      ],      "pageInfo": {        "endCursor": "TG9jYXRpb246MTgwMDI4OQ==",        "hasNextPage": false,        "total": 1      }    }  }}

次のページに進むには、pageInfo.hasNextPageがtrueである間、pageInfo.endCursorを?after=…として渡します。空のedges配列が返された場合も、そこで停止してください。各エッジにはそれぞれのcursorも含まれており、最後のエッジのcursorがそのページのendCursorであるため、どちらの値も?after=として使用できます。

ページネーション方式はエンドポイントによって異なります

上記の edges / node / pageInfo という構造は Relay カーソル方式で、3 つある方式のうちの 1 つにすぎません。

  • カーソル方式のページネーション（first、after → edges[].node と、endCursor / hasNextPage を含む pageInfo）：拠点、拠点検索、レビューの各エンドポイント（拠点ごとのインタラクションとアカウント単位の集計）で使用します。
  • オフセット方式のページネーション（page、perPage → records 配列と、totalRecords、totalPages、hasNextPage、hasPreviousPage を含む pageInfo）：接続済みアカウント、接続候補、拠点の投稿、拠点の一括投稿、アカウント全体の重複掲載情報の集計で使用します。
  • ページネーションのない単純な配列：カタログの各エンドポイント（サブカテゴリ、国と州、プランに含まれる掲載先）と拠点の写真で使用します。

ページネーションのループを書く前に、そのエンドポイントのページでレスポンス例を確認してください。オフセット方式のエンドポイントに対してカーソル方式のループを使用すると、存在しない edges キーを読み取ることになります。

次の手順

  • サンドボックスのデイパス：カード不要で拠点と掲載情報を試せます。ご自身でも AI エージェントでも利用を開始できます。
  • 認証：API キーヘッダーとキーのローテーションについて説明します。
  • エラーコード：HTTP ステータスコードとエラーレスポンスの構造について説明します。
  • SDK：型付きの Python クライアントと Node クライアントを提供します。