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

Bir listings scan alın

Özeti ve dizin bazındaki sonuçlarıyla bir listings scan döndürür; tarama devam ederken sonuçlar kısmidir.

API anahtarı gerektirir. Başlık biçimi ve anahtar yenileme için Kimlik doğrulama bölümüne bakın.

Parametreler

Yol

Ad	Tür	Zorunlu	Açıklama
scanId	string	zorunlu	The scan `id` returned by POST /listings/scans or listed by GET /listings/scans.

Yanıtlar

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 ile oluşturulmuş bir taramayı, summary değeri ve her dizin için bir results[] kaydıyla birlikte döndürür. Tarama çalışırken results, o ana kadar kontrol edilenleri içerir ve bazı kayıtlar hâlâ PENDING olabilir. status değeri COMPLETED olduğunda sonuçlar kesindir.

Kullanım senaryosu: webhook geldiğinde raporu okuma. listing_scan.completed olayı zaten taramanın tamamını içerir; bu nedenle çoğu entegrasyonda ayrıca okuma yapılması gerekmez. Bir taramayı daha sonra yeniden okumak, kontrol panelinde göstermek veya kaçırılan bir webhook sonrasında verileri almak için bu uç noktayı kullanın.

Kullanım senaryosu: webhook kullanılamadığında düzenli sorgulama. status değeri COMPLETED veya FAILED olana kadar taramayı 15 saniyede bir okuyun. Daha sık sorgulamayın: her okuma istek hızı limitinize dahil edilir. Taramalar 90 gün saklanır; bu sürenin ardından bu uç nokta, SY83005 ile birlikte 404 döndürür.

Tarama durumları

`status`	Son durum	Anlamı
`QUEUED`	hayır	Kabul edildi, henüz başlamadı. `results` boştur.
`IN_PROGRESS`	hayır	Dizinler kontrol ediliyor. `results`, kontroller ilerledikçe doldurulur.
`COMPLETED`	evet	Tüm dizinler kontrol edildi. Sonuçlar kesindir.
`FAILED`	evet	Tarama çalıştırılamadı. `failure` alanını okuyun. Kotanızdan düşülmedi.

Tarama nesnesi

Alan	Tür	Açıklama
`id`	string	Tarama kimliği. Bu uç noktada kullanın.
`status`	string	`QUEUED`, `IN_PROGRESS`, `COMPLETED` veya `FAILED`.
`source`	string	Sonuçların kaynağı: `DIRECTORY_SEARCH` (yeni bir arama), `RECENT_SCAN` (son 7 gün içinde herhangi biri tarafından taranmış, bilgileri aynı olan bir işletmenin tarama kopyası) veya `LOCATION_LISTINGS` (işletme, kendi konumlarınızdan biriyle eşleşti).
`locationId`	string veya null	Eşleşen konum. Yalnızca `source` değeri `LOCATION_LISTINGS` olduğunda ayarlanır.
`resultsAsOf`	string veya null	Dizin verilerinin toplandığı zaman. Bir `RECENT_SCAN` kopyası için bu zaman, `createdAt` değerinden öncedir. Sonuçlar oluşana kadar `null` değerindedir.
`createdAt`	string	Taramanın oluşturulduğu zaman.
`startedAt`	string veya null	Dizin kontrollerinin başladığı zaman.
`completedAt`	string veya null	Taramanın `COMPLETED` veya `FAILED` durumuna ulaştığı zaman.
`business`	object	Taranan işletme: `name`, `street`, `city`, `stateIso`, `postalCode`, `countryIso` ve `phone`. Telefon numarası uluslararası biçimde döndürülür.
`summary`	object	Sonuçların tamamına ilişkin sayılar: `total`, `found`, `accurate`, `inaccurate`, `notFound`, `pending` ve `unavailable`.
`failure`	object veya null	`status` değeri `FAILED` olduğunda ayarlanır: `code`, `message` ve buna tek bir giriş alanı neden olduysa `field`.
`results`	array	Her dizin için bir kayıt. Başarısız bir taramada boştur.

summary.found, işletmenin kayıtlı olduğu dizinlerin sayısıdır. Bunlar arasında accurate, bilgileri eşleşenlerin; inaccurate ise bilgileri eşleşmeyenlerin sayısıdır. Bulunan ve alan bazında kontrol yapılmadan doğrulanan bir işletme kaydı yalnızca found sayısına dahil edilir; bu nedenle accurate ile inaccurate toplamı, found değerinden düşük olabilir.

Bir sonuç

Alan	Tür	Açıklama
`directory`	object	Dizin: `id`, `name` ve `url`. `id`, API'nin diğer bölümlerinde kullanılan site kimliğiyle eşleşir.
`status`	string	`FOUND`, `NOT_FOUND`, `UNAVAILABLE` veya `PENDING`.
`accurate`	boolean veya null	İşletme kaydının işletmeyle eşleşip eşleşmediği. Aşağıya bakın.
`accuracySource`	string	Doğruluğun nasıl belirlendiği: `DIRECTORY_MATCH` (işletme kaydı işletmeyle karşılaştırıldı) veya `SYNC_STATUS` (kendi konumunuzun senkronizasyon durumundan alındı).
`accuracy`	object veya null	Alan bazında kontrol: her biri `{ status, message }` olan `name`, `address` ve `phone`. İşletme kaydı yoksa veya karşılaştırma yapılmadıysa `null` değerindedir.
`listing`	object veya null	Dizinde gösterilen bilgiler: `name`, `street`, `city`, `state`, `postalCode`, `country`, `fullAddress`, `phones` ve `url`. Dizinin yayımlamadığı alanlar `null` değerindedir. Bulunamadığında `null` değerindedir.
`syncStatus`	string veya null	Kendi konumunuzun bu dizindeki senkronizasyon durumu. Yalnızca `LOCATION_LISTINGS` taramalarında ayarlanır.

Sonuç status

Değer	Anlamı
`FOUND`	İşletme bu dizinde kayıtlıdır.
`NOT_FOUND`	Dizin kontrol edildi ve işletme kayıtlı değil.
`UNAVAILABLE`	Bu dizin bu sefer kontrol edilemedi. Bu, işletmenin kayıtlı olmadığı anlamına gelmez.
`PENDING`	Henüz kontrol edilmedi. Yalnızca tarama çalışırken görülür.

accurate

Değer	Anlamı
`true`	Kontrol edilen tüm bilgileri işletmeyle eşleşen, bulunmuş bir işletme kaydı.
`false`	En az bir alanı yanlış olan, bulunmuş bir işletme kaydı. Hangi alanın yanlış olduğunu görmek için `accuracy` alanını okuyun.
`null`	Bir doğruluk değerlendirmesi yok. Ya işletme bulunamadı ya da bazı dizinlerde ve yapay zekâ asistanlarında olduğu gibi, işletme bulundu ve varlığı alan bazında kontrol yapılmadan doğrulandı. Bunlar yalnızca `found` sayısına dahil edilir.

Alan bazında accuracy. name, address ve phone alanlarının her biri, değeri ACCURATE, INACCURATE veya MISSING olan bir status alanı ve farkı açıklayan bir message alanı içeren bir nesnedir; örneğin Phone number does not match. MISSING, dizinin o bilgiyi göstermediği anlamına gelir; örneğin No phone number on the listing. Dizinin gerçekte içerdiği bilgileri beklediğiniz bilgilerin yanında göstermek için listing alanını kullanın.

syncStatus. Bir LOCATION_LISTINGS taramasında doğruluk değerlendirmesi, karşılaştırmadan değil, konumunuzun gerçek işletme kaydından alınır. syncStatus, bu işletme kaydının durumudur (SYNCED, COMPLETED, IN_PROGRESS, PENDING_APPROVAL, REQUIRING_ACTION, FAILED, AVAILABLE veya CANNOT_SUBMIT) ve GET /locations/{locationId}/listings/premium ile aynı değerleri kullanır. SYNCED ve COMPLETED doğru kabul edilir.

Notlar.

Bir tarama yalnızca onu oluşturan hesap için döndürülür. Diğer tüm kimlikler için SY83005 ile birlikte 404 döndürülür.
Bazı dizinler başka bir dizinin verilerini gösterir. Örneğin Uber, Waze ve Lyft, Google Maps verilerini; CopilotAI ise Bing verilerini gösterir. Sonuçları kaynak dizinin sonucunu yansıtır ve kendilerine ait bir işletme kaydı url değeri yoktur.
UNAVAILABLE değerini olumsuz bir sonuç olarak değerlendirmeyin: dizin kontrol edilemediği için yanıt bilinmiyor.
Tarama bir RECENT_SCAN kopyası olduğunda resultsAsOf, verilerin toplandığı zamanı; createdAt ise hesabınıza kopyalandığı zamanı belirtir.

Request

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

Run in playground