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

listings scan 조회

요약과 디렉터리별 결과가 포함된 listings scan 1개를 반환하며, 스캔이 진행 중이면 일부 결과만 포함됩니다.

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로 생성한 스캔 1개를 해당 스캔의 summary 및 디렉터리별 results[] 항목과 함께 반환합니다. 스캔이 실행되는 동안 results에는 지금까지 확인한 내용이 포함되며, 일부 항목은 아직 PENDING일 수 있습니다. status이 COMPLETED이면 결과가 확정됩니다.

사용 사례: 웹훅 수신 후 보고서 조회. listing_scan.completed 이벤트에는 이미 전체 스캔이 포함되어 있으므로 대부분의 연동에서는 별도로 조회할 필요가 없습니다. 나중에 스캔을 다시 조회하거나, 대시보드에 표시하거나, 웹훅을 수신하지 못한 경우 복구하려면 이 엔드포인트를 사용하세요.

사용 사례: 웹훅을 사용할 수 없을 때 폴링. status이 COMPLETED 또는 FAILED가 될 때까지 15초마다 스캔을 조회하세요. 각 조회는 요청 빈도 제한에 포함되므로 이보다 자주 폴링하지 마세요. 스캔은 90일 동안 보관되며, 이후에는 이 엔드포인트가 404와 함께 SY83005를 반환합니다.

스캔 상태

`status`	종료 여부	의미
`QUEUED`	아니요	접수되었지만 아직 시작되지 않았습니다. `results`은 비어 있습니다.
`IN_PROGRESS`	아니요	디렉터리를 확인하고 있습니다. 진행에 따라 `results`이 채워집니다.
`COMPLETED`	예	모든 디렉터리를 확인했습니다. 결과가 확정되었습니다.
`FAILED`	예	스캔을 실행할 수 없었습니다. `failure`을 확인하세요. 사용 가능량은 차감되지 않았습니다.

스캔 객체

필드	타입	설명
`id`	string	스캔 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	디렉터리마다 항목이 1개씩 있습니다. 스캔이 실패하면 비어 있습니다.

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`	발견한 등록 정보에서 최소 1개 필드가 잘못되어 있습니다. 어떤 필드인지 확인하려면 `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