İşletme kayıtlarını listings scan ile denetleyin

İşletmenin harita, arama motoru, dizin ve AI asistanı görünümünü, dizin bazında ad, adres, telefon doğruluğunu inceleyin; webhook/polling ile sonuç alın.

Bir listings scan, bir işletmenin listingsAPI dizin ağındaki işletme kayıtlarını kontrol eder ve her dizin için işletmenin bulunup bulunmadığını, adının, adresinin ve telefon numarasının verdiğiniz bilgilerle eşleşip eşleşmediğini belirtir. İşletmenin hesabınızda bir konum olması gerekmez. Bu kılavuzda bir tarama oluşturulur, tamamlanması beklenir ve sonuçları okunur.

Şu amaçlarla kullanabilirsiniz:

• potansiyel bir müşteriyi sisteme dahil etmeden önce denetlemek, böylece ilk görüşmeye eksik veya hatalı işletme kayıtlarıyla başlamak;
• bir müşterinin işletme kayıtlarını düzeltmeden önce ve düzelttikten sonra dizinlerdeki varlığını ve NAP (ad, adres, telefon) tutarlılığını kontrol etmek;
• bir yapay zekâ ajanının, işletmeyi hesaba eklemeden "bu işletmenin kayıtları ne durumda?" sorusunu yanıtlamasını sağlamak.

1. Taramayı oluşturun

POST /listings/scans, işletmeyi tek bir input nesnesi olarak alır ve taramayı QUEUED durumunda içeren yanıtı hemen döndürür. Dizinler arka planda kontrol edilir.

curl -X POST https://listingsapi.com/api/v4/listings/scans \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d @- <<'JSON'{"input": {  "name": "Joe's Pizza",  "street": "7 Carmine Street",  "city": "New York",  "stateIso": "NY",  "postalCode": "10014",  "countryIso": "US",  "phone": "2123661182"}}JSON

Yanıt, phone uluslararası biçime dönüştürülmüş olarak taramayı döndürür. Dizinler kontrol edilene kadar results boş kalır; bu nedenle id değerini saklayın.

{  "data": {    "createListingScan": {      "reused": false,      "scan": {        "id": "TGlzdGluZ1NjYW46Mzk0YTRhNWMtZjcwMy00NjZiLTg2NjAtMDU4MTlmNDhkZjMz",        "status": "QUEUED",        "source": "DIRECTORY_SEARCH",        "locationId": null,        "resultsAsOf": null,        "createdAt": "2026-11-05T07:01:08Z",        "startedAt": null,        "completedAt": null,        "business": {          "name": "Joe's Pizza",          "street": "7 Carmine Street",          "city": "New York",          "stateIso": "NY",          "postalCode": "10014",          "countryIso": "US",          "phone": "+12123661182"        },        "summary": {          "total": 0,          "found": 0,          "accurate": 0,          "inaccurate": 0,          "notFound": 0,          "pending": 0,          "unavailable": 0        },        "failure": null,        "results": []      },      "errors": []    }  }}

Yanıt ayrıca Maliyetler, sınırlar ve hatalar bölümünde açıklanan bir quota nesnesi içerir.

Devam etmeden önce kontrol etmeniz gereken iki nokta:

• reused. Son 7 gün içinde taradığınız bir işletme için istekte bulunduğunuzda listingsAPI, yeni bir tarama başlatmak yerine önceki taramayı reused: true ve genellikle COMPLETED olan mevcut durumuyla döndürür. Kullanım hakkınızdan düşülmez ve bu tarama için yeni bir webhook gönderilmez.
• errors. Reddedilen bir istek de HTTP 200 yanıtı döndürür. Ret bilgisi data.createListingScan.errors içinde yer alır ve scan değeri null olur. Çok kısa bir telefon numarası için yanıt şöyle görünür:

{  "data": {    "createListingScan": {      "reused": false,      "scan": null,      "errors": [        {          "code": "SY83003",          "message": "SY83003: Invalid value for phone",          "contextInfo": [            {              "key": "field",              "value": "phone"            }          ]        }      ]    }  }}

contextInfo, doğrulamada başarısız olan alanın adını belirtir. Alabileceğiniz diğer kodlar hata tablosunda yer alır.

2. Sonuçları bekleyin

Bir tarama önce QUEUED durumundan IN_PROGRESS durumuna, ardından COMPLETED veya FAILED durumuna geçer. Çoğu tarama 1 ila 7 dakika içinde tamamlanır. Bir dizin yaklaşık 15 dakika sonunda yanıt vermemişse bu dizinin sonucu UNAVAILABLE olarak ayarlanır ve tarama diğer sonuçlarla tamamlanır. Mümkünse webhook kullanın ve yalnızca yedek yöntem olarak düzenli aralıklarla sorgulama yapın.

2a. Webhook'u alın (önerilir)

Tarama son durumuna ulaştığında listingsAPI, webhook URL'nize tek bir listing_scan.completed veya listing_scan.failed olayı gönderir. Olayın data.scan alanı, sonuçlar dahil olmak üzere GET tarafından döndürülen nesnenin aynısıdır; bu nedenle sonrasında ek veri almanız gerekmez.

{  "event": "listing_scan.completed",  "timestamp": "2026-11-05T07:01:52Z",  "account_id": 12345,  "data": {    "scan": {      "id": "TGlzdGluZ1NjYW46Mzk0YTRhNWMtZjcwMy00NjZiLTg2NjAtMDU4MTlmNDhkZjMz",      "status": "COMPLETED",      "summary": { "total": 62, "found": 21, "accurate": 18, "inaccurate": 2, "notFound": 41, "pending": 0, "unavailable": 0 },      "results": [ "..." ]    }  }}

Burada veri yükü kısaltılmıştır; tam örnek olay başvuru belgesinde yer alır. Olaylar, diğer tüm olaylar gibi imzalanır ve tek bir denemede, 5 saniyelik süre sınırıyla iletilir; bu nedenle başka bir işlem yapmadan önce imzayı doğrulayın, ham gövdeyi saklayın ve alındı yanıtı gönderin. Webhook'larla olaylara tepki verme bölümündeki alıcı bunu zaten yapar; tek değişiklik, event için bir koşul dalı daha eklemektir.

# After the signature check and the endpoint.verification branch:if body.get("event") in ("listing_scan.completed", "listing_scan.failed"):  inbox.put(raw)  # commit before the 200; read data.scan from the queue  return {"received": True}, 200

Bir olay yalnızca webhook'ların etkin olduğu ve doğrulanmış bir URL'ye sahip hesaplara gönderilir. Hesabınız bu koşulları karşılamıyorsa veya bir olay hiç ulaşmazsa taramayı düzenli aralıklarla sorgulayın; tarama her iki durumda da 90 gün saklanır. İmzalama ayrıntıları İmzalar ve doğrulama bölümünde yer alır.

2b. Yedek yöntem olarak düzenli aralıklarla sorgulayın

GET /listings/scans/{scanId}, taramayı o ana kadar elde edilen sonuçlarla birlikte döndürür. Tarama sürerken dizinler yanıt verdikçe results dolar ve summary.pending henüz yanıt vermeyen dizinlerin sayısını gösterir. 15 saniyede bir sorgulayın, daha sık sorgulamayın; her istek istek hızı sınırınıza dahil edilir.

SCAN_ID="TGlzdGluZ1NjYW46Mzk0YTRhNWMtZjcwMy00NjZiLTg2NjAtMDU4MTlmNDhkZjMz" while true; doscan=$(curl -s "https://listingsapi.com/api/v4/listings/scans/$SCAN_ID" \  -H "Authorization: API $LISTINGSAPI_KEY")status=$(echo "$scan" | jq -r '.data.listingScan.status')echo "status: $status"case "$status" in  COMPLETED|FAILED)    echo "$scan" | jq '.data.listingScan | {status, summary, failure}'    break ;;  null)    echo "$scan"    break ;;esacsleep 15done

Sonuçları yakın zamanda yapılan bir taramadan veya kendi konumlarınızdan birinden alınan bir tarama, oluşturulduğu anda COMPLETED durumundadır; bu nedenle tek bir GET yeterlidir.

3. Sonuçları okuyun

Tamamlanan bir tarama, bir summary ve kontrol edilen her dizin için results içinde bir öğe içerir; ülkeye bağlı olarak bu sayı yaklaşık 60'a kadar çıkabilir. business, gönderdiğiniz girdiyi phone uluslararası biçime dönüştürülmüş olarak döndürür.

{  "total": 62,  "found": 21,  "accurate": 18,  "inaccurate": 2,  "notFound": 41,  "pending": 0,  "unavailable": 0}

total, dizin sayısıdır. found, işletmenin kaydının bulunduğu dizin sayısıdır ve accurate, inaccurate ile aşağıda açıklanan, yalnızca varlığı doğrulanan işletme kayıtlarından oluşur. notFound, işletmenin kaydının bulunmadığı dizin sayısıdır. unavailable, bu sefer kontrol edilemeyen dizinlerin sayısını gösterir; pending ise yalnızca tarama sürerken sıfırdan farklıdır.

Her sonuç, dizin için bir status içerir:

FOUND durumundaki bir sonuçta accurate, işletme kaydının girdinizle eşleşip eşleşmediğini belirtir:

• true, ad, adres ve telefon bilgilerinin tümünün eşleştiği anlamına gelir.
• false, bunlardan en az birinin eşleşmediği anlamına gelir. İşletme kaydında yer almayan bir alan da eşleşmeme olarak değerlendirilir; bu nedenle telefon numarası olmayan bir işletme kaydı false durumundadır.
• null, işletmenin bulunduğu ancak alan bazında kontrol yapılmadığı anlamına gelir.

accuracy, name, address ve phone alanlarının her biri için bir status ve bir message ile değerlendirmeyi açıklar. status değeri ACCURATE, INACCURATE veya MISSING olur; alan doğru olduğunda message değeri null olur. Aşağıda, ad ve adres bilgileri eşleşen ancak telefon numarası bulunmayan bir Facebook sayfası gösterilmektedir:

{  "directory": {    "id": 184,    "name": "Facebook",    "url": "facebook.com"  },  "status": "FOUND",  "accurate": false,  "accuracySource": "DIRECTORY_MATCH",  "accuracy": {    "name": {      "status": "ACCURATE",      "message": null    },    "address": {      "status": "ACCURATE",      "message": null    },    "phone": {      "status": "MISSING",      "message": "No phone number on the listing"    }  },  "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": [],    "url": "https://www.facebook.com/177353602413952"  },  "syncStatus": null}

Bazı dizinler yalnızca işletmenin var olduğunu doğrular ve karşılaştırma için yeterli ayrıntı göstermez. Bunlar, accurate: null ile birlikte FOUND durumunda döner ve yalnızca found sayısına dahil edilir; accurate veya inaccurate sayısına dahil edilmez. Bu işletme kayıtlarını mevcut olarak değerlendirin, doğrulanmış olarak değerlendirmeyin:

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

NOT_FOUND durumundaki bir sonuçta ne listing ne de accuracy bulunur:

{  "directory": {    "id": 352,    "name": "YellowPages",    "url": "www.yellowpages.com"  },  "status": "NOT_FOUND",  "accurate": null,  "accuracySource": "DIRECTORY_MATCH",  "accuracy": null,  "listing": null,  "syncStatus": null}

Bazı dizinler kendi verilerini tutmaz. Uber, Waze ve Lyft, Google Maps verilerini; Copilot ise Bing verilerini gösterir. Sonuçları kaynak dizinin sonuçlarını yansıtır; bu nedenle genellikle Google Maps veya Bing tarafından döndürülen sonuçları tekrarlar ve işletme kaydı için url içermez. Bunları summary içinde ayrı öğeler olarak sayın, ancak bağımsız bir doğrulama olarak yorumlamayın:

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

ChatGPT ve Gemini gibi yapay zekâ asistanları da dahildir. Bunlar için listing, asistanın işletme hakkında bildiklerini gösterir; bu bilgiler genellikle yalnızca ad, tam adres ve telefon numarasından oluşur ve alan bazında accuracy bulunmaz.

Tamamlanan bir taramadan bir düzeltme listesi oluşturmak için yanlış veya eksik alan içeren her dizini yazdırın:

curl -s https://listingsapi.com/api/v4/listings/scans/TGlzdGluZ1NjYW46Mzk0YTRhNWMtZjcwMy00NjZiLTg2NjAtMDU4MTlmNDhkZjMz \-H "Authorization: API $LISTINGSAPI_KEY" \| jq -r '.data.listingScan.results[]         | select(.accurate == false)         | .directory.name as $directory         | .accuracy         | to_entries[]         | select(.value.status != "ACCURATE")         | $directory + " " + .key + ": " + (.value.message // .value.status)'

Joe's Pizza taraması için bu işlem iki satır yazdırır: Facebook'ta telefon numarası yoktur ve Judys Book farklı bir telefon numarası gösterir.

Facebook phone: No phone number on the listingJudys Book phone: Phone number does not match

Sonuçların kaynağı

source, tarama sonuçlarının nasıl elde edildiğini belirtir; resultsAsOf ise verilerin toplandığı zamandır.

Maliyetler, sınırlar ve hatalar

Yalnızca yeni bir DIRECTORY_SEARCH taraması aylık kotanızdan düşülür; bu kota planınıza bağlıdır ve fatura döneminizle birlikte sıfırlanır. Şunlar ücretsizdir:

• aynı işletmenin taramasını 7 gün içinde tekrarlamak. Daha önce yaptığınız tarama reused: true ile döndürülür;
• aynı işletme için herhangi bir hesap tarafından yakın zamanda yapılan bir taramanın sonuçlarını kullanabilen bir tarama. Bu, bir RECENT_SCAN kopyasıdır;
• kendi konumlarınızdan biriyle eşleşen taramalar (LOCATION_LISTINGS);
• FAILED durumuyla sonuçlanan ve kullanılan kotası iade edilen taramalar.

Taramalar 90 gün boyunca saklanır. Bu sürenin ardından GET, SY83005 ile birlikte 404 döndürür.

Oluşturma ve listeleme yanıtları bir quota nesnesi içerir; böylece bir toplu işlem başlatmadan önce kota durumunuzu görebilirsiniz. Listeleme, taramalarınızı en yenisi önce olacak şekilde, perPage ile sayfa başına 1 ile 50 sonuç içeren sayfalar halinde, results olmadan döndürür.

curl -s "https://listingsapi.com/api/v4/listings/scans?page=1&perPage=20" \-H "Authorization: API $LISTINGSAPI_KEY" \| jq '.data.listingScans.quota'

En sık karşılaşacağınız hatalar şunlardır. Oluşturma işlemi, hatalarını HTTP 200 ile yanıt gövdesinde döndürür; alma ve listeleme işlemleri ise normal HTTP durum kodunu döndürür.

Mevcut olmayan bir id için GET şu yanıtı döndürür:

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

FAILED durumuyla sonuçlanan bir taramanın nedeni failure alanında bulunur ve results boş kalır:

{  "status": "FAILED",  "failure": {    "code": "SY83010",    "message": "SY83010: Listing scans are temporarily unavailable, try again later",    "field": null  }}

Genel hata biçimi Hata kodları bölümünde açıklanmıştır.

Yapay zekâ ajanları için

Barındırılan MCP sunucusu bu özelliği üç araç aracılığıyla sunar: listings_scans_create, listings_scans_get ve listings_scans_list. Bir asistan, kullanıcının adını verdiği işletme için bir tarama başlatabilir, listings_scans_get ile durumunu düzenli aralıklarla sorgulayabilir ve ilgilenilmesi gereken dizinleri özetleyebilir. REST ile olduğu gibi, tarama oluşturmak için bir Write anahtarı gerekir. Kurulum, Yapay zekâ ajanlarını listingsAPI MCP sunucusuna bağlayın bölümünde açıklanmıştır.

Sonraki adımlar

• Webhook'larla olaylara yanıt verin: tarama olaylarının ulaştığı alıcı.
• İşletme kaydı durumunu ve yayındaki bağlantıları kontrol edin ve İşletme kaydı hatalarını bulun ve düzeltin: bir işletme hesabınıza konum olarak eklendikten sonra işletme kayıtlarını takip edin ve düzeltin.
• Konum ekleyin: denetlediğiniz işletmeyi sisteme ekleyin.
• Başvuru: listings scan oluşturun, listings scan alın, listings scans listeleyin, Olay başvurusu, Hata kodları.