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

Dapatkan listings scan

Mengembalikan satu listings scan beserta ringkasan dan hasil per direktori, dengan data parsial selama pemindaian masih berlangsung.

Memerlukan kunci API. Lihat Autentikasi untuk format header dan rotasi kunci.

Parameter

Path

Nama	Tipe	Wajib	Deskripsi
scanId	string	wajib	The scan `id` returned by POST /listings/scans or listed by GET /listings/scans.

Respons

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.

Mengembalikan satu pemindaian yang dibuat oleh POST /listings/scans, beserta summary dan satu entri results[] untuk setiap direktori. Selama pemindaian berjalan, results berisi hasil yang sudah diperiksa sejauh ini, dan beberapa entri mungkin masih bernilai PENDING. Ketika status bernilai COMPLETED, hasilnya sudah final.

Kasus penggunaan: membaca laporan setelah webhook diterima. Peristiwa listing_scan.completed sudah menyertakan seluruh data pemindaian, sehingga sebagian besar integrasi tidak perlu melakukan pembacaan sama sekali. Gunakan endpoint ini untuk membaca ulang pemindaian di lain waktu, menampilkannya di dasbor, atau mengambil datanya jika webhook terlewat.

Kasus penggunaan: polling saat webhook tidak tersedia. Baca pemindaian setiap 15 detik hingga status bernilai COMPLETED atau FAILED. Jangan melakukan polling lebih sering: setiap pembacaan diperhitungkan dalam batas laju permintaan Anda. Pemindaian disimpan selama 90 hari; setelah itu, endpoint ini mengembalikan 404 dengan SY83005.

Status pemindaian

`status`	Status akhir	Arti
`QUEUED`	tidak	Diterima, belum dimulai. `results` kosong.
`IN_PROGRESS`	tidak	Direktori sedang diperiksa. `results` terisi seiring berlangsungnya pemeriksaan.
`COMPLETED`	ya	Semua direktori sudah diperiksa. Hasilnya sudah final.
`FAILED`	ya	Pemindaian tidak dapat dijalankan. Baca `failure`. Pemindaian ini tidak menggunakan kuota Anda.

Objek pemindaian

Field	Tipe	Deskripsi
`id`	string	ID pemindaian. Gunakan ID ini pada endpoint ini.
`status`	string	`QUEUED`, `IN_PROGRESS`, `COMPLETED`, atau `FAILED`.
`source`	string	Sumber hasil: `DIRECTORY_SEARCH` (pencarian baru), `RECENT_SCAN` (salinan hasil pemindaian bisnis yang identik, yang dilakukan oleh siapa pun dalam 7 hari terakhir), atau `LOCATION_LISTINGS` (bisnis cocok dengan salah satu lokasi Anda sendiri).
`locationId`	string atau null	Lokasi yang cocok. Hanya diisi ketika `source` bernilai `LOCATION_LISTINGS`.
`resultsAsOf`	string atau null	Waktu pengumpulan data direktori. Untuk salinan `RECENT_SCAN`, waktu ini lebih awal daripada `createdAt`. Bernilai `null` hingga hasil tersedia.
`createdAt`	string	Waktu pembuatan pemindaian.
`startedAt`	string atau null	Waktu dimulainya pemeriksaan direktori.
`completedAt`	string atau null	Waktu pemindaian mencapai status `COMPLETED` atau `FAILED`.
`business`	object	Bisnis yang dipindai: `name`, `street`, `city`, `stateIso`, `postalCode`, `countryIso`, dan `phone`. Nomor telepon dikembalikan dalam format internasional.
`summary`	object	Jumlah pada seluruh hasil: `total`, `found`, `accurate`, `inaccurate`, `notFound`, `pending`, dan `unavailable`.
`failure`	object atau null	Diisi ketika `status` bernilai `FAILED`: `code`, `message`, dan, jika penyebabnya adalah satu field input, `field`.
`results`	array	Satu entri per direktori. Kosong jika pemindaian gagal.

summary.found menghitung direktori tempat bisnis terdaftar. Dari direktori tersebut, accurate menghitung direktori yang detailnya cocok dan inaccurate menghitung direktori yang detailnya tidak cocok. Profil bisnis yang ditemukan dan dikonfirmasi tanpa pemeriksaan per field hanya dihitung dalam found, sehingga jumlah accurate ditambah inaccurate bisa lebih kecil daripada found.

Satu hasil

Field	Tipe	Deskripsi
`directory`	object	Direktori: `id`, `name`, dan `url`. `id` sama dengan ID situs yang digunakan di bagian lain API.
`status`	string	`FOUND`, `NOT_FOUND`, `UNAVAILABLE`, atau `PENDING`.
`accurate`	boolean atau null	Apakah profil bisnis cocok dengan bisnis tersebut. Lihat di bawah.
`accuracySource`	string	Cara akurasi ditentukan: `DIRECTORY_MATCH` (profil bisnis dibandingkan dengan bisnis tersebut) atau `SYNC_STATUS` (diambil dari status sinkronisasi lokasi Anda sendiri).
`accuracy`	object atau null	Pemeriksaan per field: `name`, `address`, dan `phone`, masing-masing `{ status, message }`. Bernilai `null` jika tidak ada profil bisnis atau tidak ada perbandingan.
`listing`	object atau null	Data yang ditampilkan direktori: `name`, `street`, `city`, `state`, `postalCode`, `country`, `fullAddress`, `phones`, dan `url`. Field yang tidak dipublikasikan oleh direktori bernilai `null`. Bernilai `null` jika tidak ditemukan.
`syncStatus`	string atau null	Status sinkronisasi lokasi Anda sendiri di direktori ini. Hanya diisi pada pemindaian `LOCATION_LISTINGS`.

status hasil

Nilai	Arti
`FOUND`	Bisnis terdaftar di direktori ini.
`NOT_FOUND`	Direktori sudah diperiksa dan bisnis tidak terdaftar.
`UNAVAILABLE`	Direktori ini tidak dapat diperiksa kali ini. Hal ini tidak berarti bisnis tidak terdaftar.
`PENDING`	Belum diperiksa. Hanya muncul selama pemindaian berjalan.

accurate

Nilai	Arti
`true`	Profil bisnis yang ditemukan dengan semua detail yang diperiksa cocok dengan bisnis tersebut.
`false`	Profil bisnis yang ditemukan dengan setidaknya satu field yang salah. Baca `accuracy` untuk melihat field mana yang salah.
`null`	Tidak ada kesimpulan. Bisnis tidak ditemukan, atau bisnis ditemukan dan keberadaannya dikonfirmasi tanpa pemeriksaan per field, seperti pada beberapa direktori dan asisten AI. Hasil ini hanya dihitung dalam `found`.

accuracy per field. Masing-masing dari name, address, dan phone adalah objek dengan status bernilai ACCURATE, INACCURATE, atau MISSING, serta message yang menjelaskan perbedaannya, misalnya Phone number does not match. MISSING berarti direktori tidak menampilkan detail tersebut, misalnya No phone number on the listing. Gunakan listing untuk menampilkan data yang sebenarnya tersimpan di direktori berdampingan dengan data yang Anda harapkan.

syncStatus. Pada pemindaian LOCATION_LISTINGS, kesimpulan berasal dari profil bisnis aktual lokasi Anda, bukan dari perbandingan. syncStatus adalah status profil bisnis tersebut (SYNCED, COMPLETED, IN_PROGRESS, PENDING_APPROVAL, REQUIRING_ACTION, FAILED, AVAILABLE, atau CANNOT_SUBMIT), dengan nilai yang sama seperti GET /locations/{locationId}/listings/premium. SYNCED dan COMPLETED dianggap akurat.

Catatan.

Pemindaian hanya dikembalikan untuk akun yang membuatnya. Untuk ID lainnya, endpoint mengembalikan 404 dengan SY83005.
Beberapa direktori menampilkan data dari direktori lain. Misalnya, Uber, Waze, dan Lyft menampilkan data Google Maps, sedangkan CopilotAI menampilkan data Bing. Hasilnya sama dengan direktori sumber dan tidak memiliki url profil bisnis tersendiri.
Jangan menganggap UNAVAILABLE sebagai hasil negatif: direktori tidak dapat diperiksa, sehingga jawabannya belum diketahui.
Jika pemindaian berupa salinan RECENT_SCAN, resultsAsOf adalah waktu pengumpulan data, dan createdAt adalah waktu data disalin ke akun Anda.

Request

curl -X GET 'https://listingsapi.com/api/v4/listings/scans/<scanId>' \  -H "Authorization: API $LISTINGSAPI_KEY"

Run in playground