listings scanを作成

1つの事業者のスキャンを開始します。このスキャンでは、Google、Bing、Apple Maps、Yelp、Facebook、MapQuestなどの地図サービスや検索エンジン、データアグリゲーターや地域のディレクトリ、ChatGPTやGeminiなどのAIアシスタントで構成されるディレクトリネットワーク全体を対象に、事業者の掲載の有無と掲載情報の正確性を監査します。国によって異なりますが、1回のスキャンで最大約60のディレクトリを確認します。事業者がアカウント内の拠点である必要はありません。そのため、見込み顧客や導入前の顧客を監査できます。

呼び出しは、スキャンがQUEUEDステータスの状態ですぐに戻ります。ディレクトリの確認はバックグラウンドで実行され、結果はGET /listings/scans/{scanId}で取得します。

使用例：見込み顧客の掲載情報の監査。 営業ツールで事業者名、住所、電話番号を収集します。スキャンを作成し、返されたscan.idを保存して、listing_scan.completedイベントを受信したらdata.scanから完了したスキャンを取得します。summaryには概要（事業者が見つかったディレクトリの数と、そのうち掲載情報が正確なディレクトリの数）が含まれ、results[]にはレポートに表示するディレクトリごとの詳細が含まれます。

使用例：管理中の事業者の状態確認。 自分のアカウント内の拠点の事業者情報をスキャンします。スキャンはその拠点を認識し、再検索する代わりに、その拠点の実際の掲載情報から結果を生成します（再利用と無料スキャンを参照）。

スキャンが終了するまでの流れ

スキャンはQUEUED、IN_PROGRESSの順に進み、COMPLETEDまたはFAILEDで終了します。ほとんどのスキャンは1〜7分で完了します。約15分経過してもディレクトリから応答がない場合、そのディレクトリの結果はUNAVAILABLEに設定され、他の結果を含めてスキャンが完了します。

• Webhookの使用を推奨します。 listing_scan.completedイベントとlisting_scan.failedイベントはスキャンごとに1回配信され、GET /listings/scans/{scanId}が返すものと同じスキャンオブジェクトが結果を含めて渡されます。これらのイベントは、Webhookが有効で、Webhook URLが検証済みのアカウントに、他のすべてのイベントと同様に署名付きで送信されます。listing_scan.completedを参照してください。
• 代替手段としてポーリングを使用します。 Webhookを受信できない場合は、statusがCOMPLETEDまたはFAILEDになるまで、15秒ごとにスキャンを取得してください。これより短い間隔でポーリングしても効果はなく、リクエストの割り当てを消費します。

必須フィールド

name、street、city、countryIso、phoneは常に必須です。次の2つのフィールドは、国によって必須かどうかが異なります。

値が欠落しているか形式が不正な場合はSY83003で拒否され、エラーにフィールド名が示されます。phoneは6〜15桁の数字、countryIsoは2文字の英字である必要があります。

再利用と無料スキャン

スキャンで常に新しい検索が実行されるわけではありません。返されたスキャンのsourceフィールドは、結果の取得元を示します。

7日以内に同じ事業者を再度スキャンすると、新しいスキャンの代わりにアカウント内の既存のスキャンが返され、レスポンスにはreused: trueが含まれます。新しいスキャンは開始されず、新しいWebhookも送信されないため、別のイベントを待つのではなく、返されたスキャンを確認してください（まだ実行中の場合もあります）。再利用期間内に自分のアカウント内の拠点を再度スキャンした場合も、同じ動作になります。

月間利用枠

Listings scans は有料プランに含まれ、月間利用枠はプランによって異なります。無料のサンドボックス用デイパスでは利用できません。利用枠を消費するのは、新規の DIRECTORY_SEARCH スキャンのみです。以下は無料です。

• 7 日以内に同じビジネスを再度スキャンする場合（reused: true）、
• RECENT_SCAN のコピー、
• LOCATION_LISTINGS スキャン、
• 失敗したスキャンは、利用枠にカウントされません。

利用枠はアカウントの請求期間に合わせてリセットされます。作成リクエストへのすべてのレスポンスには、リクエストが拒否された場合も含め、limit、used、remaining、resetsAt を含む quota が返されます。プランとアドオンを参照してください。

エラー

作成リクエストが拒否されると、scan: null と、errors[] に格納された理由を含む HTTP 200 が返されるため、ステータスコードだけでなく errors を確認してください。読み取り専用キーではスキャンを作成できません。これがリクエストレベルでの唯一の失敗であり、SY90016 を含む HTTP 400 が返されます。

コードの全一覧はエラーコードにあります。

注意事項。

• リクエストボディは、input オブジェクトで囲む必要があります。
• HTTP ステータスではなく errors を確認してください。 作成リクエストが拒否されると、HTTP 200 が返されます。
• 電話番号はスキャンの実行前に正規化され、書式、大文字と小文字、または空白だけが異なる 2 つのリクエストは、同じビジネスとして扱われます。
• 作成リクエストは、スキャンで確認するディレクトリの数にかかわらず、レート制限に対して 1 リクエストとしてカウントされます。
• スキャンは 90 日間保持されます。その後は、スキャンの読み取りで SY83005 を含む 404 が返されます。
• この呼び出しには Write（書き込み）キーが必要です。