GET
/api/v4/listings/scans/{scanId}listings scanを取得
1件のlistings scanを概要およびディレクトリごとの結果とともに返しますが、スキャンの実行中は部分的な結果を返します。
パラメーター
パス
| 名前 | 型 | 必須 | 説明 |
|---|---|---|---|
| scanId | string | 必須 | The scan `id` returned by POST /listings/scans or listed by GET /listings/scans. |
レスポンス
200A completed scan. The real response lists every directory in `results`, usually around 60. This example is trimmed to six entries, one of each kind described below.
{ "data": { "listingScan": { "id": "TGlzdGluZ1NjYW46Mzk0YTRhNWMtZjcwMy00NjZiLTg2NjAtMDU4MTlmNDhkZjMz", "status": "COMPLETED", "source": "DIRECTORY_SEARCH", "locationId": null, "resultsAsOf": "2026-11-05T07:01:51Z", "createdAt": "2026-11-05T07:01:08Z", "startedAt": "2026-11-05T07:01:11Z", "completedAt": "2026-11-05T07:01:51Z", "business": { "name": "Joe's Pizza", "street": "7 Carmine Street", "city": "New York", "stateIso": "NY", "postalCode": "10014", "countryIso": "US", "phone": "+12123661182" }, "summary": { "total": 62, "found": 21, "accurate": 18, "inaccurate": 2, "notFound": 41, "pending": 0, "unavailable": 0 }, "failure": null, "results": [ { "directory": { "id": 1, "name": "Google Maps", "url": "maps.google.com" }, "status": "FOUND", "accurate": true, "accuracySource": "DIRECTORY_MATCH", "accuracy": { "name": { "status": "ACCURATE", "message": null }, "address": { "status": "ACCURATE", "message": null }, "phone": { "status": "ACCURATE", "message": null } }, "listing": { "name": "Joe's Pizza", "street": "7 Carmine Street", "city": "New York", "state": "NY", "postalCode": "10014", "country": "US", "fullAddress": "7 Carmine St, New York, NY 10014, USA", "phones": [ "+1 212-366-1182" ], "url": "https://maps.google.com/?cid=4877966330195296067" }, "syncStatus": null }, { "directory": { "id": 2, "name": "Yelp", "url": "yelp.com" }, "status": "FOUND", "accurate": true, "accuracySource": "DIRECTORY_MATCH", "accuracy": { "name": { "status": "ACCURATE", "message": null }, "address": { "status": "ACCURATE", "message": null }, "phone": { "status": "ACCURATE", "message": null } }, "listing": { "name": "Joe's Pizza", "street": "7 Carmine St", "city": "New York", "state": "NY", "postalCode": "10014", "country": "US", "fullAddress": "7 Carmine St, New York, NY 10014", "phones": [ "+12123661182" ], "url": "https://www.yelp.com/biz/joes-pizza-new-york-4" }, "syncStatus": null }, { "directory": { "id": 374, "name": "Map Quest", "url": "www.mapquest.com" }, "status": "FOUND", "accurate": null, "accuracySource": "DIRECTORY_MATCH", "accuracy": { "name": { "status": "ACCURATE", "message": null }, "address": { "status": "MISSING", "message": "Not shown" }, "phone": { "status": "MISSING", "message": "Not shown" } }, "listing": { "name": "Joe's Pizza", "street": "7 Carmine St", "city": "New York", "state": "NY", "postalCode": "10014", "country": null, "fullAddress": "7 Carmine St, New York, NY 10014, US", "phones": [], "url": null }, "syncStatus": null }, { "directory": { "id": 352, "name": "YellowPages", "url": "www.yellowpages.com" }, "status": "NOT_FOUND", "accurate": null, "accuracySource": "DIRECTORY_MATCH", "accuracy": null, "listing": null, "syncStatus": null }, { "directory": { "id": 50, "name": "Judys Book", "url": "judysbook.com" }, "status": "FOUND", "accurate": false, "accuracySource": "DIRECTORY_MATCH", "accuracy": { "name": { "status": "ACCURATE", "message": null }, "address": { "status": "ACCURATE", "message": null }, "phone": { "status": "INACCURATE", "message": "Phone number does not match" } }, "listing": { "name": "Joe's Pizza", "street": "7 CARMINE ST", "city": "New York", "state": "NY", "postalCode": "10014", "country": null, "fullAddress": "7 CARMINE ST, New York, NY 10014", "phones": [ "8553685707" ], "url": "https://www.judysbook.com/Joes-Pizza-Uncategorized-newyork-r29271293.htm" }, "syncStatus": null }, { "directory": { "id": 350, "name": "Uber", "url": "uber.com" }, "status": "FOUND", "accurate": true, "accuracySource": "DIRECTORY_MATCH", "accuracy": { "name": { "status": "ACCURATE", "message": null }, "address": { "status": "ACCURATE", "message": null }, "phone": { "status": "ACCURATE", "message": null } }, "listing": { "name": "Joe's Pizza", "street": "7 Carmine Street", "city": "New York", "state": "NY", "postalCode": "10014", "country": "US", "fullAddress": "7 Carmine St, New York, NY 10014, USA", "phones": [ "+1 212-366-1182" ], "url": null }, "syncStatus": null } ] } }}200A failed scan. `failure` has the code and message, and `results` is empty.
{ "data": { "listingScan": { "id": "TGlzdGluZ1NjYW46ZGVkZTNhOTgtNDA5Ni00ZDI3LWJlMjUtMzY3YTYxOTk4Y2Y1", "status": "FAILED", "source": "DIRECTORY_SEARCH", "locationId": null, "resultsAsOf": null, "createdAt": "2026-11-03T08:53:18Z", "startedAt": null, "completedAt": "2026-11-03T08:53:18Z", "business": { "name": "Franklin Barbecue", "street": "900 E 11th St", "city": "Austin", "stateIso": "TX", "postalCode": "78702", "countryIso": "US", "phone": "+15126531187" }, "summary": { "total": 0, "found": 0, "accurate": 0, "inaccurate": 0, "notFound": 0, "pending": 0, "unavailable": 0 }, "failure": { "code": "SY83010", "message": "SY83010: Listing scans are temporarily unavailable, try again later", "field": null }, "results": [] } }}401Unauthenticated, missing or invalid API key.
404No scan with that ID on this account, or the scan is older than 90 days (`SY83005`).
{ "data": { "listingScan": null }, "errors": [ { "message": "SY83005: Listing scan not found" } ]}429Rate limit exceeded. Retry after the `Retry-After` header value.
POST /listings/scansで作成されたスキャンを1件返します。スキャンにはsummaryと、各ディレクトリのresults[]エントリが含まれます。スキャンの実行中は、resultsにその時点までの確認結果が格納され、一部のエントリはまだPENDINGの場合があります。statusがCOMPLETEDになると、結果が確定します。
使用例：Webhookの受信後にレポートを読み取る。 listing_scan.completedイベントにはすでにスキャン全体が含まれているため、ほとんどの連携では読み取りは不要です。後からスキャンを再取得する場合、ダッシュボードに表示する場合、またはWebhookを受信できなかった場合に、このエンドポイントを使用します。
使用例：Webhookを利用できない場合にポーリングする。 statusがCOMPLETEDまたはFAILEDになるまで、15秒ごとにスキャンを読み取ります。これより短い間隔でポーリングしないでください。読み取りは毎回レート制限の対象になります。スキャンは90日間保持され、その後はこのエンドポイントがSY83005を伴う404を返します。
スキャンのステータス
スキャンオブジェクト
summary.foundは、ビジネスが掲載されているディレクトリの数です。そのうち、詳細情報が一致するディレクトリの数がaccurate、一致しないディレクトリの数がinaccurateです。フィールドごとの確認を行わずに存在が確認された掲載情報はfoundにのみ計上されるため、accurateとinaccurateの合計がfoundを下回る場合があります。
個別の結果
結果のstatus
accurate
フィールドごとのaccuracy。 name、address、phoneはそれぞれオブジェクトで、ACCURATE、INACCURATE、MISSINGのいずれかを値とするstatusと、相違点を説明するmessage（例：Phone number does not match）を持ちます。MISSINGは、ディレクトリがその詳細情報を表示していないことを意味します（例：No phone number on the listing）。listingを使用すると、ディレクトリに実際に登録されている情報を、想定していた情報と並べて表示できます。
syncStatus。 LOCATION_LISTINGSのスキャンでは、比較によってではなく、自分のアカウントの拠点の実際の掲載情報に基づいて判定されます。syncStatusはその掲載情報の状態（SYNCED、COMPLETED、IN_PROGRESS、PENDING_APPROVAL、REQUIRING_ACTION、FAILED、AVAILABLE、CANNOT_SUBMITのいずれか）であり、GET /locations/{locationId}/listings/premiumと同じ値を使用します。SYNCEDとCOMPLETEDは正確とみなされます。
注意事項。
- スキャンは、それを作成したアカウントにのみ返されます。それ以外のIDを指定すると、
SY83005を伴う404が返されます。 - 一部のディレクトリは、別のディレクトリのデータを表示します。たとえば、Uber、Waze、LyftはGoogle Mapsのデータを表示し、CopilotAIはBingのデータを表示します。これらの結果には参照元のディレクトリの結果が反映され、独自の掲載情報の
urlはありません。 UNAVAILABLEを未掲載と判断しないでください。ディレクトリを確認できなかったため、掲載の有無は不明です。- スキャンが
RECENT_SCANのコピーの場合、resultsAsOfはデータが収集された日時、createdAtは自分のアカウントにコピーされた日時です。
Request
curl -X GET 'https://listingsapi.com/api/v4/listings/scans/<scanId>' \ -H "Authorization: API $LISTINGSAPI_KEY"