Listings APIListings API
サインイン

国・州・カテゴリを調べる

拠点を作成する前に、サポートされている国と州のコードを取得し、ビジネスカテゴリに対応する数値の ID を調べ、プランに含まれる掲載先を確認します。

拠点の作成には、API から取得する必要がある3種類の値があります。API が受け付ける countryIso と stateIso、数値の subCategoryId、そして掲載先を限定する場合はプランに含まれるサイトの ID です。これらは3つのカタログエンドポイントから取得できます。いずれもページネーションのない単純な配列を返します。

1. 国と州のコードを一覧表示する

GET /countries は、サポートされているすべての国について、ISO コード、hasCity フラグ、states 配列を返します。iso の値は、作成時と更新時の countryIso と stateIso に使用します。Python SDK では client.countries()、Node SDK では client.fetchCountries() として提供されています。

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

hasCity: true は作成時に city が必須であることを意味し、false の場合は送信した市区町村が破棄されます。stateRequired: true は stateIso が必須で、その国の states のいずれかでなければならないことを意味し、false の場合は省略してください。hasPostalCode: true はその国で郵便番号が使われていることを意味するため、住所とともに postalCode を送信してください。各フラグについては、国のエンドポイントで説明しています。

2. カテゴリの ID を調べる

GET /sub-categories はカテゴリカタログ全体を返します。subCategoryId として送信する値は、base64 の id ではなく、整数の databaseId です。たとえば、Restaurants は 1432 です。サーバー側の検索パラメーターはないため、クライアント側のコードでリストを名前で絞り込んでください。

Find a category
curl https://listingsapi.com/api/v4/sub-categories \-H "Authorization: API $LISTINGSAPI_KEY" \| jq '.data.subcategories[] | select(.name | test("restaurant"; "i")) | {databaseId, name, primary}'
JSON
{  "data": {    "subcategories": [      {        "databaseId": 1432,        "id": "U3ViQ2F0ZWdvcnk6MTQzMg==",        "key": "restaurants",        "name": "Restaurants",        "primary": true      }    ]  }}
フィールド用途
databaseIdsubCategoryId として送信する整数、または最大9個のセカンダリカテゴリを指定するために additionalCategoryIds 内で送信する整数です。
name選択画面に表示し、照合に使用する、人が読めるラベルです。
keyURL に適した形式の名前のスラッグで、名前が変更されても変わりません。
primaryそのカテゴリを拠点のプライマリサブカテゴリにできるかどうかを示します。subCategoryId には true の項目のみを選択してください。

3. プランに含まれる掲載先を確認する

GET /plan-sites は、プランに含まれるすべての掲載先について、数値の id、url、対応する国、hideAddress が適用される国を一覧で返します。作成時の enabledSiteIds と更新時の submissionDisabledSiteIds に指定できるのは、これらの ID のみです。拠点の国で絞り込み、その拠点を受け付ける掲載先だけを選択肢として提示してください。

Plan sites
curl https://listingsapi.com/api/v4/plan-sites \-H "Authorization: API $LISTINGSAPI_KEY" \| jq '.data.planSites[] | select(.supportedCountries | index("US")) | {id, name, url}'
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": 2,        "name": "Yelp",        "url": "yelp.com",        "supportedCountries": ["US", "CA", "GB", "DE", "FR"],        "hideAddressSupportedCountries": ["US", "CA", "AU", "GB"]      }    ]  }}

ここでは両方の国の配列を省略していますが、実際のレスポンスにはサイトごとに50個以上のコードが含まれることがあります。非店舗型ビジネスの場合は、その国に対応している掲載先でも番地を含む住所のない掲載情報を受け付けないことがあるため、hideAddressSupportedCountries も確認してください。

4. 取得結果をキャッシュする

3つのカタログはいずれも変更が少なく、ページネーションもないため、起動時にそれぞれ1回取得し、メモリまたは小さなテーブルに保存して、定期的に更新してください。作成のたびに処理内でこれらを呼び出すと、新しいデータが返されないままレート制限を消費します。Launch プランでは、1分あたり10件のリクエスト枠のうち3件を消費することになります。

カタログサイズ更新のタイミング
国数十の国、数百の州ほとんど不要です。1日1回で十分です。
サブカテゴリ約6,000件毎日、または不明な subCategoryId が原因で作成に失敗したときです。
プランに含まれるサイト数十の掲載先リストの範囲はプランに限定されるため、プランを変更したときです。

サブカテゴリについては小文字の name から databaseId へのマップを、国については countryIso から states へのマップを作成してください。作成の呼び出し前にキャッシュと照合して住所を検証し、サポートされていない countryIso（SY10036）や city の欠落（SY10126）を、リクエストの送信前にアプリケーション内で検出できるようにしてください。

次の手順