GET/api/v4/listings/scans/{scanId}

取得 listings scan

傳回單筆 listings scan，包含摘要及各目錄的結果；掃描仍在執行時，僅提供部分結果。

需要 API 金鑰。標頭格式與金鑰輪替請參閱驗證。

參數

路徑

名稱	類型	必填	說明
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.

Response

{  "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.

Response

{  "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`).

Response

{  "data": {    "listingScan": null  },  "errors": [    {      "message": "SY83005: Listing scan not found"    }  ]}

429Rate limit exceeded. Retry after the `Retry-After` header value.

傳回由 POST /listings/scans 建立的一次掃描，包含其 summary，以及每個目錄各自的 results[] 項目。掃描執行期間，results 會包含目前已完成檢查的內容，部分項目可能仍為 PENDING。當 status 為 COMPLETED 時，結果即為最終結果。

使用情境：收到 webhook 後讀取報告。 listing_scan.completed 事件已包含完整的掃描資料，因此大多數整合完全不需要另外讀取。您可以使用此端點在之後重新讀取掃描、在儀表板中顯示掃描，或在漏收 webhook 時補取資料。

使用情境：無法使用 webhook 時進行輪詢。 每 15 秒讀取一次掃描，直到 status 為 COMPLETED 或 FAILED。請勿以更高的頻率輪詢：每次讀取都會計入您的速率限制。掃描會保留 90 天；之後此端點會回傳 404，並附上 SY83005。

掃描狀態

`status`	是否為終止狀態	意義
`QUEUED`	否	已接受，尚未開始。`results` 為空。
`IN_PROGRESS`	否	正在檢查各個目錄。`results` 會隨著檢查進度逐步填入。
`COMPLETED`	是	已檢查所有目錄。結果即為最終結果。
`FAILED`	是	掃描無法執行。請讀取 `failure`。此次掃描未使用您的配額。

掃描物件

欄位	型別	說明
`id`	string	掃描 ID。請在此端點使用此 ID。
`status`	string	`QUEUED`、`IN_PROGRESS`、`COMPLETED` 或 `FAILED`。
`source`	string	結果來源：`DIRECTORY_SEARCH`（重新搜尋）、`RECENT_SCAN`（複製任何人在過去 7 天內對同一商家執行的掃描）或 `LOCATION_LISTINGS`（商家符合您自己的某個地點）。
`locationId`	string 或 null	符合的地點。僅在 `source` 為 `LOCATION_LISTINGS` 時設定。
`resultsAsOf`	string 或 null	目錄資料的收集時間。若為 `RECENT_SCAN` 副本，此時間會早於 `createdAt`。在有結果之前為 `null`。
`createdAt`	string	掃描的建立時間。
`startedAt`	string 或 null	開始檢查目錄的時間。
`completedAt`	string 或 null	掃描進入 `COMPLETED` 或 `FAILED` 狀態的時間。
`business`	object	接受掃描的商家：`name`、`street`、`city`、`stateIso`、`postalCode`、`countryIso` 和 `phone`。電話號碼會以國際格式傳回。
`summary`	object	各項結果的統計數量：`total`、`found`、`accurate`、`inaccurate`、`notFound`、`pending` 和 `unavailable`。
`failure`	object 或 null	在 `status` 為 `FAILED` 時設定：包含 `code`、`message`，若是由某個輸入欄位造成，還會包含 `field`。
`results`	array	每個目錄各有一個項目。掃描失敗時為空。

summary.found 統計刊登了該商家資訊的目錄數量。其中，accurate 統計詳細資料相符的目錄數量，inaccurate 則統計不相符的目錄數量。若找到的商家資訊已確認存在，但未逐一比對欄位，則只會計入 found，因此 accurate 加上 inaccurate 可能小於 found。

單筆結果

欄位	型別	說明
`directory`	object	目錄：`id`、`name` 和 `url`。`id` 與 API 其他地方使用的網站 ID 相同。
`status`	string	`FOUND`、`NOT_FOUND`、`UNAVAILABLE` 或 `PENDING`。
`accurate`	boolean 或 null	商家資訊是否與商家相符。請參閱下方說明。
`accuracySource`	string	判定準確性的方式：`DIRECTORY_MATCH`（將商家資訊與商家資料比對）或 `SYNC_STATUS`（取自您自己地點的同步狀態）。
`accuracy`	object 或 null	各欄位的檢查結果：`name`、`address` 和 `phone`，每個都是 `{ status, message }`。沒有商家資訊或未進行比對時為 `null`。
`listing`	object 或 null	目錄顯示的內容：`name`、`street`、`city`、`state`、`postalCode`、`country`、`fullAddress`、`phones` 和 `url`。目錄未公開的欄位為 `null`。找不到商家資訊時為 `null`。
`syncStatus`	string 或 null	您自己的地點在此目錄上的同步狀態。僅在 `LOCATION_LISTINGS` 掃描中設定。

結果 status

值	意義
`FOUND`	此目錄刊登了該商家的資訊。
`NOT_FOUND`	已檢查此目錄，且未刊登該商家的資訊。
`UNAVAILABLE`	此次無法檢查此目錄。這不表示該商家的資訊未被刊登。
`PENDING`	尚未檢查。只會在掃描執行期間出現。

accurate

值	意義
`true`	已找到商家資訊，且所有經過檢查的詳細資料都與商家相符。
`false`	已找到商家資訊，但至少有一個欄位不正確。請讀取 `accuracy`，查看哪些欄位不正確。
`null`	無法判定。可能是找不到商家，或是已找到並確認商家資訊存在，但未逐一比對欄位，例如部分目錄及 AI 助理的情況。這些結果只會計入 `found`。

各欄位的 accuracy。 name、address 和 phone 各自都是物件，其中 status 的值為 ACCURATE、INACCURATE 或 MISSING，並包含用來說明差異的 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 時，此端點會回傳 404，並附上 SY83005。
部分目錄會顯示其他目錄的資料。例如，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"

Run in playground