Listings APIListings API
サインイン

補助 API

補助 API の全エンドポイントを、cURL、Python、Node のサンプルとともに紹介します。対象は、サポートされている国と州、サブカテゴリカタログ、ご利用のプランに含まれる掲載先サイトです。

補助エンドポイントは、API のほかの部分で検証に使用される3つの参照カタログです。サポートされている国と州、存在するビジネスカテゴリ、ご利用のプランに含まれる掲載先ディレクトリを確認できます。3つとも読み取り専用で、ページネーションはなく、常に全件を返すため、Read（読み取り）キーで十分であり、ページネーションよりもキャッシュが重要です。

エンドポイントの概要

メソッドパス機能リファレンス
GET/countriesサポートされているすべての国と、その州および ISO コードを返します。サポートされている国と州の一覧を取得
GET/sub-categories約6,000件のビジネスカテゴリを含むカタログ全体を返します。サブカテゴリの一覧を取得
GET/plan-sitesご利用のプランに含まれるすべての掲載先ディレクトリを返します。プランに含まれるサイトの一覧を取得

サポートされている国と州の一覧を取得

GET /countries

data.supportedCountries にカタログ全体を返します。各国には、ISO コード、base64 形式の id、数値の databaseId、各要素に固有の ISO コードを持つ states 配列、および3つの住所フラグが含まれます。住所フラグは、hasCity（市区町村が必須）、stateRequired（州が必須で、states に照らして検証されます）、hasPostalCode（その国で郵便番号が使用されます）です。地域区分のない国では、空の states 配列を返します。

パラメーター

このエンドポイントはパラメーターを受け取りません。常に全件を返します。

Countries
curl https://listingsapi.com/api/v4/countries \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "supportedCountries": [      {        "databaseId": 13,        "hasCity": true,        "id": "Q291bnRyeToxMw==",        "iso": "AU",        "name": "Australia",        "states": [          { "countryId": 13, "id": "139", "iso": "VIC", "name": "Victoria" },          { "countryId": 13, "id": "142", "iso": "NSW", "name": "New South Wales" }        ]      },      {        "databaseId": 17,        "hasCity": true,        "id": "Q291bnRyeToxNw==",        "iso": "BE",        "name": "Belgium",        "states": []      }    ]  }}

必要な値は、2つの iso フィールドです。作成時と更新時には、国の iso を countryIso として、州の iso を stateIso として使用します。書き込みの前に両方をこの一覧に照らして検証すれば、サーバー側の 400 が発生する代わりに、自社のフォームで明確なメッセージを表示できます。

サブカテゴリの一覧を取得

GET /sub-categories

data.subcategories に約6,000件のカテゴリレコードを、ページネーションのない単一の配列として返します。自由形式のテキストとして把握している業種を、拠点の書き込みで必要となる数値 ID に変換するための参照データです。

パラメーター

ありません。呼び出すたびにカタログ全体が返されます。

Subcategories
curl https://listingsapi.com/api/v4/sub-categories \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "subcategories": [      {        "databaseId": 4589,        "id": "U3ViQ2F0ZWdvcnk6NDU4OQ==",        "key": "3d-printing-service",        "name": "3D printing service",        "primary": true      }    ]  }}

各レコードには5つのフィールドがあり、どれを使用するかは用途によって異なります。

フィールド用途
databaseIdsubCategoryId として、また additionalCategoryIds 内で渡す整数値です。
id同じレコードの base64 形式の識別子です。
key名前を URL で扱いやすい形式にしたスラッグです。
nameユーザーに表示するラベルです。
primaryそのカテゴリを拠点のメインのサブカテゴリに指定できるかどうかを示します。

拠点には、subCategoryId にメインカテゴリを1つ、additionalCategoryIds に追加のカテゴリを最大9つ指定できます。

プランに含まれるサイトの一覧を取得

GET /plan-sites

アカウントのプランに含まれるすべての掲載先ディレクトリを、data.planSites に返します。これは数値のサイト ID の正式な一覧であり、API のほかの部分でも、ここに含まれる ID のみが有効です。

パラメーター

ありません。レスポンスの範囲は、アカウントのプランに限定されます。

Plan sites
curl https://listingsapi.com/api/v4/plan-sites \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "planSites": [      {        "id": 1,        "name": "Google Maps",        "url": "maps.google.com",        "supportedCountries": ["US", "CA", "IN", "GB", "DE"],        "hideAddressSupportedCountries": ["US", "CA", "AU", "IN", "GB"]      },      {        "id": 184,        "name": "Facebook",        "url": "facebook.com",        "supportedCountries": ["US", "CA", "IN", "GB", "DE"],        "hideAddressSupportedCountries": ["US", "CA", "AU", "IN", "GB"]      }    ]  }}

2つの国配列は、それぞれ異なる情報を提供します。supportedCountries はサイトが掲載情報を受け付ける国を示すため、掲載先を選択肢として提示する前に、拠点の countryIso で絞り込んでください。hideAddressSupportedCountries はサイトが住所の非表示設定に対応する国を示し、これは非店舗型ビジネスに必要な情報です。どちらの配列にも50以上のコードが含まれる場合があり、上記のサンプルでは一部を省略しています。

サイト ID は安定しており、覚えておくと便利です。1 は Google Maps、184 は Facebook を表し、この2つの掲載先はほとんどの接続フローの対象です。

独立したエンドポイントはありません。プレイスアクションリンクは、Google の オンラインで注文、席を予約、来店予約 などのボタンで、プラットフォームでは個別のリソースではなく、拠点のフィールドとして管理されます。作成時と更新時に placeActionLinks 配列で設定し、拠点を読み取る任意のエンドポイントから取得できます。

各エントリには placeActionType と uri が必要で、任意の isPreferred フラグを指定できますが、優先リンクはタイプごとに最大 1 つです。また、更新時には action に add または delete を指定できます。有効なタイプ、削除ルール、同期の動作については、すべて プレイスアクションリンク に記載されています。

発生するエラー

コードまたはステータス意味対処方法
401キーがないか、無効です。Authorization: API <YOUR_API_KEY> を送信してください。
Retry-After を伴う 429これらのカタログは、アカウントのレート制限を共有します。結果をキャッシュしてください。レート制限 を参照してください。
countries での 500サーバー側の障害であり、不正なリクエストではありません。バックオフを適用して再試行してください。呼び出し内容を修正する必要はありません。

これらのエンドポイントはいずれも書き込みを行わないため、ここで Read キーを使用しても SY90016 が返されることはありません。完全な一覧は エラーコード にあります。

次の手順