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 均为对象，包含值为 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 请求时，端点返回 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