掲載情報

すべての掲載情報エンドポイントを、cURL、Python、Nodeのサンプルとともに紹介します。対象は、プレミアム掲載先の同期ステータス、音声アシスタント、拠点単位およびアカウント単位の重複検出、重複の非表示化です。

掲載情報とは、1つの掲載先ディレクトリに登録された1つの拠点の情報です。拠点を作成すると、プランに含まれる掲載先ごとに掲載情報がキューに追加され、掲載情報エンドポイントで各掲載情報の状態を取得し、検出された重複を一覧表示して、重複として確定するか誤検出として除外できます。4つのGETエンドポイントはRead（読み取り）キーで利用でき、2つのPOSTエンドポイントにはWrite（書き込み）キーが必要です。

エンドポイント一覧

プレミアム掲載情報のステータスの取得

GET /locations/{locationId}/listings/premium

拠点のプランに含まれるプレミアム掲載先ごとに、1件のレコードをdata.listingsForLocation内に返します。ページネーション形式のリストではなく、通常の配列です。同じ階層のパス/listings/additionalは無料ディレクトリを同じ形式で返しますが、listingTypeクエリパラメーターは存在せず、そこに値を送信しても無視されます。

パラメーター

curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "listingsForLocation": [      {        "id": "TGlzdGluZzoxMDQ0Njg3MjM=",        "site": { "databaseId": "1", "name": "Google Maps", "url": "maps.google.com" },        "syncStatus": "REQUIRING_ACTION",        "displayStatus": "Connect your account to sync the listing",        "actionRequired": true,        "listingUrl": null,        "syncIssue": null,        "lastUpdate": "2026-07-06T18:33:28Z"      },      {        "id": "TGlzdGluZzoxMDQ0Njg3Mjc=",        "site": { "databaseId": "387", "name": "BeLocalFocussed", "url": "belocalfocussed.com" },        "syncStatus": "SYNCED",        "displayStatus": "Synced",        "actionRequired": false,        "listingUrl": "https://belocalfocussed.com/jenny-home-26x0ffkd0e",        "syncIssue": null,        "lastUpdate": "2026-07-06T18:33:30Z"      },      {        "id": "TGlzdGluZzoxMDQ0Njg3MDk=",        "site": { "databaseId": "301", "name": "Local Mint", "url": "localmint.com" },        "syncStatus": "FAILED",        "displayStatus": "Partner experiencing issues; awaiting response",        "actionRequired": false,        "listingUrl": null,        "syncIssue": "Publisher requires website URL",        "lastUpdate": "2026-07-06T18:34:03Z"      }    ]  }}

syncStatusに基づいて処理を分岐してください。displayStatusをユーザーに表示し、syncIssueで掲載先側の理由を確認し、lastUpdateで送信処理の停滞を検出してください。listingUrlは公開済みの行にのみ設定されます。

Google Maps、Facebook、Wazeは、対応するアカウントが接続されるまで、displayStatus: "Connect your account to sync the listing"を伴うREQUIRING_ACTIONの状態のままです。これは新しい拠点では想定どおりの状態です。

音声アシスタントのステータスの取得

GET /locations/{locationId}/voice-assistants

Google Assistant、Amazon Alexa、Apple Siri、Microsoft Cortana、Samsung Bixbyの各音声アシスタントについて、1件のレコードをdata.voiceAssistantsForLocation内に返します。通常の配列で、ステータスの種類はプレミアムエンドポイントよりも少なくなっています。

パラメーター

curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/voice-assistants \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "voiceAssistantsForLocation": [      {        "databaseId": "104468723",        "voiceIdentifier": "GOOGLE_ASSISTANT",        "name": "Google Assistant",        "connectedAccountId": null,        "syncStatus": "REQUIRING_ACTION",        "actionRequired": true,        "syncIssue": null,        "errors": []      },      {        "databaseId": "104468711",        "voiceIdentifier": "SIRI",        "name": "Siri",        "connectedAccountId": null,        "syncStatus": "IN_PROGRESS",        "actionRequired": false,        "syncIssue": null,        "errors": []      }    ]  }}

actionRequiredがtrueであるか、syncIssueが設定されているすべての行にフラグを付けてください。errorsには掲載先側のエラー文字列が格納され、同期に使用される接続済みアカウントがある場合は、connectedAccountIdでそのアカウントが示されます。Google Assistantの結果はGoogle Business Profileの接続から取得されるため、対応が必要になる最も一般的な理由は、Googleへの接続がないことです。Siriの結果は、拠点のApple Maps掲載情報から取得されます。

アカウント全体の重複を集計する

GET /locations/listings/duplicates

すべての拠点と掲載先にわたり、キーで参照できる検出済みの重複をすべて data.duplicateListingsRollup 配下に返します。オフセット方式のページネーションを使用し、page と perPage を入力すると、records[] に加えて pageInfo.totalRecords、pageInfo.totalPages、pageInfo.hasNextPage が返されます。フィルターは JSON ではなく、フラットなクエリパラメーターです。何も指定しない場合、status のデフォルト値は POTENTIAL、tag のデフォルト値は all となるため、パラメーターなしで呼び出すと、そのアカウントの未解決の重複が返されます。

パラメーター

Python と Node のラッパーで利用できるのは、tag と page のみです。status または siteId で絞り込む場合、または perPage を設定する場合は、重複する掲載情報の処理 に示すように、ルートを直接呼び出してください。

curl "https://listingsapi.com/api/v4/locations/listings/duplicates?status=POTENTIAL&page=1&perPage=50" \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "duplicateListingsRollup": {      "pageInfo": {        "hasNextPage": true,        "hasPreviousPage": false,        "totalPages": 34,        "totalRecords": 1673      },      "records": [        {          "id": "3329229",          "name": "Woodbury Train Station",          "nameValid": false,          "duplicateProcessingState": "POTENTIAL",          "liveLink": "http://citysquares.com/b/woodbury-train-station-23598450",          "locationId": "73451",          "siteName": "City Squares",          "siteUrl": "citysquares.com"        }      ]    }  }}

集計結果から重複の所在を確認でき、各レコードには locationId と siteName が記載されています。duplicateProcessingState は、拠点単位のエンドポイントが status として返すものと同じライフサイクルステータスです。hasNextPage が false になるまで 1 ページずつ取得してください。待機を挟まないループでは、すぐに 429 に達してしまいます。

1 つの拠点の重複を一覧表示する

GET /locations/{locationId}/listings/duplicates

1 つの拠点で検出された重複をすべて、掲載先サイトごとにグループ化して data.duplicateListingsForLocation 配下に返します。単純な配列です。各グループは listings 配列を持つサイト（name、url）で、各エントリには、両方の mark エンドポイントが受け取る listingItemId が含まれます。空の配列は、何も検出されなかったことを意味します。

パラメーター

curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/listings/duplicates \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "duplicateListingsForLocation": [      {        "id": "U2l0ZToxNTA=",        "name": "City Squares",        "url": "citysquares.com",        "listings": [          {            "id": "RHVwbGljYXRlOjIzNTk4NDUw",            "listingItemId": "TGlzdGluZ0l0ZW06MjM1OTg0NTA=",            "name": "Woodbury Train Station",            "liveLink": "http://citysquares.com/b/woodbury-train-station-23598450",            "status": "POTENTIAL"          }        ]      }    ]  }}

liveLink を開いてエントリを確認し、listingItemId を保持してください。Node SDK では、フラット化された d.id が後続の呼び出しに渡す値です。status は、上記のアカウント全体の集計と同じ 4 つの値を使用します。

掲載情報の項目を重複として確定する

POST /locations/listings/mark-as-duplicate

掲載先で非表示にできるよう、掲載情報の項目に確認済みの重複としてフラグを付けます。listingItemId の値を input 配下で送信し、項目ごとに呼び出すのではなく、1 つの拠点で確認済みのすべての項目を 1 回の呼び出しにまとめてください。これは書き込み操作であり、Write（書き込み）キーが必要です。

パラメーター

curl -X POST https://listingsapi.com/api/v4/locations/listings/mark-as-duplicate \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "listingItemIds": ["TGlzdGluZ0l0ZW06MjM1OTg0NTA="]  }}'

{  "data": {    "markAsDuplicate": {      "success": true,      "errors": null    }  }}

success: true は、項目が受け付けられ、PROCESSING に移行することを意味します。success: false を伴う 200、または 400 には errors 配列が含まれ、その各エントリには code、message、path が含まれます。通常の原因は、不明な ID または形式が不正な ID です。Python SDK はペイロードを返しますが、Node SDK は代わりに ValidationError をスローするため、Promise が解決された場合は成功したことを意味します。

掲載情報の項目を重複ではないとして除外する

POST /locations/listings/mark-as-not-duplicate

重複の候補を誤検出として除外します。検出では見落としを避けるため、同じフランチャイズの別店舗、正当な 2 つ目のプロフィール、または名称を変更した拠点にもフラグが付きます。除外すると、その項目は両方の重複取得エンドポイントに表示されなくなります。上記のエンドポイントと同一の body を受け取り、誤ってフラグを付けた項目を元に戻す場合にも使用します。

パラメーター

curl -X POST https://listingsapi.com/api/v4/locations/listings/mark-as-not-duplicate \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "listingItemIds": ["TGlzdGluZ0l0ZW06MjM1OTg0NTA="]  }}'

{  "data": {    "markAsNotDuplicate": {      "success": true,      "errors": null    }  }}

レスポンスは data.markAsNotDuplicate で、重複としてマークする呼び出しと同じ success フィールドと errors フィールドを含みます。除外された項目は、重複ではないことが確認済みとして記録され、次回の検出処理でも再び表示されることはありません。

発生するエラー

すべてのコードはエラーリファレンスに記載されています。

次の手順

• 掲載情報のステータスと公開リンクを確認する：premium エンドポイントと voice エンドポイントを使って、掲載状況を把握するダッシュボードを作成します。
• 掲載情報のエラーを見つけて修正する：REQUIRING_ACTIONとFAILEDの行を順に処理します。
• 重複する掲載情報に対処する：ステータスの追跡を含め、重複を扱う4つのエンドポイントを使ってレビューを繰り返す手順を説明します。
• Google に接続して拠点をインポートする：Google Maps と Google Assistant が使用する Google Business Profile に接続します。
• Apple Business Connect に接続する：オーナーの確認済み Apple Business アカウントを通じて Apple Maps に公開します。
• リソースのトップページ：掲載情報。SDK リファレンス：Python の掲載情報、Node の掲載情報。