Bir listings scan oluşturun

Tek bir işletme için tarama başlatır. Tarama, işletmenin dizin ağı genelinde kayıtlı olup olmadığını ve kayıt bilgilerinin doğruluğunu denetler: Google, Bing, Apple Maps, Yelp, Facebook ve MapQuest gibi harita ve arama hizmetleri, veri toplayıcıları ve yerel dizinler ile ChatGPT ve Gemini gibi yapay zekâ asistanları. Ülkeye bağlı olarak bir tarama yaklaşık 60 dizine kadar kontrol yapar. İşletmenin hesabınızda bir konum olması gerekmez; böylece potansiyel bir müşteriyi veya henüz sisteme dahil etmediğiniz bir müşteriyi denetleyebilirsiniz.

Çağrı, taramayı QUEUED durumunda hemen döndürür. Dizin kontrolleri arka planda çalışır ve sonuç GET /listings/scans/{scanId} ile okunur.

Kullanım örneği: potansiyel bir müşteri için işletme kaydı denetimi. Satış aracınız işletme adını, adresini ve telefon numarasını toplar. Bir tarama oluşturun, döndürülen scan.id değerini saklayın ve listing_scan.completed olayı geldiğinde tamamlanan taramayı data.scan üzerinden okuyun. summary, özeti (işletmenin kaç dizinde bulunduğunu ve bu dizinlerden kaçındaki bilgilerin doğru olduğunu), results[] ise raporda gösterilecek dizin bazındaki ayrıntıları sağlar.

Kullanım örneği: zaten yönettiğiniz bir işletmenin durumunu kontrol etme. Kendi konumlarınızdan birinin işletme bilgilerini tarayın. Tarama bu konumu tanır ve yeniden arama yapmak yerine sonuçlarını o konumun gerçek işletme kayıtlarından oluşturur (bkz. Yeniden kullanım ve ücretsiz taramalar).

Tarama nasıl tamamlanır

Bir tarama sırasıyla QUEUED ve IN_PROGRESS durumlarından geçer, ardından COMPLETED veya FAILED durumuyla sona erer. Çoğu tarama 1 ila 7 dakika içinde tamamlanır. Bir dizin yaklaşık 15 dakika sonra hâlâ yanıt vermemişse o dizinin sonucu UNAVAILABLE olarak ayarlanır ve tarama diğer sonuçlarla tamamlanır.

• Webhook kullanmayı tercih edin. listing_scan.completed ve listing_scan.failed olayları, GET /listings/scans/{scanId} tarafından döndürülen tarama nesnesinin aynısıyla, sonuçlar dahil olmak üzere, tarama başına bir kez iletilir. Bu olaylar, diğer tüm olaylar gibi imzalanarak webhook'ları etkinleştirilmiş ve webhook URL'si doğrulanmış hesaplara gönderilir. Bkz. listing_scan.completed.
• Alternatif olarak düzenli aralıklarla sorgulayın. Webhook alamıyorsanız status değeri COMPLETED veya FAILED olana kadar taramayı her 15 saniyede bir okuyun. Daha sık sorgulamak hiçbir fayda sağlamaz ve istek kotanızı tüketir.

Zorunlu alanlar

name, street, city, countryIso ve phone her zaman zorunludur. İki alanın zorunluluğu ülkeye bağlıdır:

Eksik veya hatalı biçimlendirilmiş bir değer SY83003 ile reddedilir ve hata mesajında alanın adı belirtilir. phone 6 ila 15 rakamdan, countryIso ise iki harften oluşmalıdır.

Yeniden kullanım ve ücretsiz taramalar

Bir tarama her zaman yeni bir arama yapmaz. Döndürülen taramadaki source alanı, sonuçların kaynağını belirtir:

Aynı işletmeyi 7 gün içinde yeniden tararsanız yeni bir tarama yerine hesabınızdaki mevcut tarama döndürülür ve yanıtta reused: true yer alır. Yeni bir tarama başlatılmaz ve yeni bir webhook gönderilmez; bu nedenle başka bir olay beklemek yerine döndürülen taramayı okuyun (tarama hâlâ devam ediyor olabilir). Kendi konumlarınızdan birini yeniden kullanım süresi içinde tekrar taradığınızda da aynı davranış geçerlidir.

Aylık kota

Listings scans, ücretli planlara planınıza bağlı bir aylık kotayla dahildir. Ücretsiz test ortamı günlük erişiminde kullanılamaz. Yalnızca yeni bir DIRECTORY_SEARCH taraması kotadan düşülür. Şunlar ücretsizdir:

• aynı işletme için 7 gün içinde tekrarlanan bir tarama (reused: true),
• bir RECENT_SCAN kopyası,
• bir LOCATION_LISTINGS taraması,
• başarısız olan ve kotadan düşülmeyen bir tarama.

Kota, hesabınızın faturalandırma dönemiyle birlikte sıfırlanır. İsteğin reddedildiği durumlar dahil, her oluşturma yanıtı limit, used, remaining ve resetsAt içeren quota içerir. Planlar ve eklentiler bölümüne bakın.

Hatalar

Reddedilen bir oluşturma isteği, scan: null içeren ve nedeni errors[] içinde belirtilen bir HTTP 200 döndürür; bu nedenle yalnızca durum kodunu değil, errors değerini de kontrol edin. Salt okunur anahtarlar tarama oluşturamaz: bu, istek düzeyindeki tek hatadır ve SY90016 içeren bir HTTP 400 döndürür.

Kodların tam listesi Hata kodları bölümündedir.

Notlar.

• İstek gövdesi bir input nesnesi içine yerleştirilmelidir.
• HTTP durumunu değil, errors değerini kontrol edin. Reddedilen bir oluşturma isteği HTTP 200 döndürür.
• Tarama çalıştırılmadan önce telefon numaraları standart biçime dönüştürülür ve yalnızca biçimlendirme, büyük/küçük harf kullanımı veya boşluklar açısından farklı olan iki istek aynı işletmeye ait sayılır.
• Taramanın kaç dizini kontrol ettiğinden bağımsız olarak, bir oluşturma isteği istek hızı sınırınızdan bir istek kullanır.
• Bir tarama 90 gün boyunca saklanır. Bu süreden sonra taramayı okuma isteği, SY83005 içeren bir 404 döndürür.
• Bu çağrı için bir Write (yazma) anahtarı gerekir.