Crea un listings scan

Avvia una scansione di un'attività. La scansione verifica se l'attività è presente nella rete di directory e quanto sono accurati i suoi dati: mappe e motori di ricerca come Google, Bing, Apple Maps, Yelp, Facebook e MapQuest, aggregatori di dati e directory locali, e assistenti AI come ChatGPT e Gemini. A seconda del paese, una scansione controlla fino a circa 60 directory. L'attività non deve necessariamente essere una sede nel tuo account, quindi puoi verificare un potenziale cliente o un cliente prima dell'onboarding.

La chiamata restituisce immediatamente la scansione nello stato QUEUED. I controlli delle directory vengono eseguiti in background e il risultato si legge con GET /listings/scans/{scanId}.

Caso d'uso: una verifica delle schede di un potenziale cliente. Il tuo strumento di vendita raccoglie il nome, l'indirizzo e il numero di telefono di un'attività. Crea una scansione, salva il valore scan.id restituito e leggi la scansione completata da data.scan quando arriva l'evento listing_scan.completed. summary fornisce il riepilogo (quante directory hanno trovato l'attività e quante di queste riportano dati accurati), mentre results[] fornisce i dettagli per ciascuna directory da mostrare nel report.

Caso d'uso: un controllo dello stato di un'attività che gestisci già. Esegui una scansione dei dati di una delle tue sedi. La scansione la riconosce e genera i risultati a partire dalle schede effettive di quella sede, anziché eseguire una nuova ricerca (vedi Riutilizzo e scansioni gratuite).

Come termina una scansione

Una scansione passa attraverso gli stati QUEUED e IN_PROGRESS e termina nello stato COMPLETED o FAILED. La maggior parte delle scansioni si completa in un intervallo compreso tra 1 e 7 minuti. Se una directory non ha risposto dopo circa 15 minuti, il suo risultato viene impostato su UNAVAILABLE e la scansione si completa con gli altri risultati.

• Preferisci il webhook. Gli eventi listing_scan.completed e listing_scan.failed vengono inviati una volta per scansione, con lo stesso oggetto di scansione restituito da GET /listings/scans/{scanId}, risultati inclusi. Vengono inviati agli account che hanno i webhook abilitati e un URL del webhook verificato, e sono firmati come tutti gli altri eventi. Vedi listing_scan.completed.
• Usa il polling come alternativa. Se non puoi ricevere webhook, leggi la scansione ogni 15 secondi finché status non è COMPLETED o FAILED. Un polling più frequente non offre alcun vantaggio e consuma la tua quota di richieste.

Campi obbligatori

name, street, city, countryIso e phone sono sempre obbligatori. L'obbligatorietà di 2 campi dipende dal paese:

Un valore mancante o non valido viene rifiutato con SY83003 e l'errore indica il nome del campo. phone deve contenere da 6 a 15 cifre e countryIso deve essere composto da 2 lettere.

Riutilizzo e scansioni gratuite

Una scansione non esegue sempre una nuova ricerca. Il campo source della scansione restituita indica la provenienza dei risultati:

Se esegui di nuovo una scansione della stessa attività entro 7 giorni, viene restituita la scansione esistente nel tuo account anziché una nuova, con reused: true nella risposta. Non viene avviata alcuna nuova scansione e non viene inviato alcun nuovo webhook, quindi leggi la scansione restituita (potrebbe essere ancora in corso) anziché attendere un altro evento. Lo stesso comportamento si applica quando esegui di nuovo una scansione di una delle tue sedi entro il periodo di riutilizzo.

Quota mensile

Le Listings scans sono incluse nei piani a pagamento con una quota mensile che dipende dal tuo piano. Non sono disponibili con un pass giornaliero gratuito per la sandbox. Solo una nuova scansione DIRECTORY_SEARCH viene conteggiata nella quota. Sono gratuite:

• una scansione ripetuta della stessa attività entro 7 giorni (reused: true),
• una copia RECENT_SCAN,
• una scansione LOCATION_LISTINGS,
• una scansione non riuscita, che non viene conteggiata.

La quota si rinnova in base al periodo di fatturazione del tuo account. Ogni risposta a una richiesta di creazione include quota con limit, used, remaining e resetsAt, anche quando la richiesta viene rifiutata. Consulta Piani e componenti aggiuntivi.

Errori

Una richiesta di creazione rifiutata restituisce HTTP 200 con scan: null e il motivo in errors[], quindi controlla errors e non solo il codice di stato. Le chiavi di sola lettura non possono creare scansioni: questo è l'unico errore a livello di richiesta e restituisce HTTP 400 con SY90016.

L'elenco completo dei codici è disponibile in Codici di errore.

Note.

• Il corpo della richiesta deve essere racchiuso in un oggetto input.
• Controlla errors, non lo stato HTTP. Una richiesta di creazione rifiutata restituisce HTTP 200.
• I numeri di telefono vengono normalizzati prima dell'esecuzione della scansione e due richieste che differiscono solo per formattazione, maiuscole e minuscole o spazi vengono considerate relative alla stessa attività.
• Una richiesta di creazione conta come una richiesta ai fini del tuo limite di frequenza, indipendentemente dal numero di directory controllate dalla scansione.
• Una scansione viene conservata per 90 giorni. Trascorso questo periodo, la sua lettura restituisce 404 con SY83005.
• Questa chiamata richiede una chiave Write (scrittura).