tiktok-ad-library/
search

Scopri i record pubblicitari pubblici supportati di TikTok con una sola query per nome dell’inserzionista o parola chiave, poi raccogli identità normalizzate, date di visualizzazione, segnali sul pubblico e riferimenti ai media, quando disponibili.

TikTok Ad Library Search API

Inserzionista o parola chiave
Pagine da 12 record
Scoperta degli annunci pubblici
0,5 crediti per risultato
Pronto
Pronto

Inserisci i parametri e invia una richiesta. Qui compariranno lo stato dell’attività e i risultati normalizzati.

README

A cura di SocQ · Aggiornato il

TikTok Ad Library Search

TikTok Ad Library Search invia una sola query per nome dell’inserzionista o parola chiave alla Ads Library pubblica e segue il suo cursore opaco fino al limite richiesto, allineato alle pagine, o a una condizione di arresto a monte. Supporta la ricerca sulla trasparenza e la scoperta degli annunci, non la gestione privata delle campagne né la misurazione delle prestazioni.

Funzionalità della TikTok Ad Library Search API

  • Una sola query mirataCerca con un solo nome di inserzionista, termine di brand o parola chiave obbligatorio e non vuoto.
  • Raccolta allineata alle pagineRichiedi da 12 a 2.000 risultati in multipli di 12; 1.992 è il valore valido più alto.
  • Gestione del cursore opacoSegue i cursori della fonte fino al limite, a una pagina vuota, a un segnale di fine, a un cursore mancante o a un cursore ripetuto.
  • Riepiloghi normalizzati degli annunciRicevi campi stabili su identità, inserzionista, date di visualizzazione, diffusione, destinazione, impression, media, pubblicazione e raccolta.
  • Valori nulli legati alla fonteMantiene i campi null o vuoti quando il risultato di ricerca pubblico espone solo un riepilogo o omette quel valore.

Parametri della TikTok Ad Library Search API

ParametriObbligatorioDescrizione
queryObbligatorioNome di inserzionista o parola chiave obbligatorio e non vuoto. Viene accettata esattamente una query.
results_limitFacoltativoLimite facoltativo di risultati. Il valore predefinito è 12 e deve essere un multiplo di 12 da 12 a 2.000; il valore valido più alto è 1.992.

Come usare la TikTok Ad Library Search API

Invia una query e un limite valido allineato alle pagine, interroga l’attività asincrona e usa le pagine di risultati normalizzati.

  1. Scegli un solo nome di inserzionista o una sola parola chiave; l’endpoint non accetta un elenco di query.
  2. Invia con POST query e un results_limit facoltativo a /v1/tiktok-ad-library/search.
  3. Interroga /v1/tasks/{task_id} finché l’attività non raggiunge uno stato finale.
  4. Leggi data.results.items e segui i cursori del risultato dell’attività quando la risposta indica altre pagine.
curl -X POST "https://api.socq.ai/v1/tiktok-ad-library/search" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"Anysphere","results_limit":12}'

# Poll GET /v1/tasks/{task_id}
# Read normalized ads from data.results.items

Casi d’uso della TikTok Ad Library Search API

  • Scoperta degli inserzionisti: Trova gli annunci pubblici supportati associati al nome di un inserzionista o di un brand inviato.
  • Ricerca per parole chiave: Crea un insieme di annunci pubblici da esaminare i cui contenuti indicizzati nella libreria corrispondono a un termine tematico.
  • Revisione del panorama creativo: Confronta temi visibili, riferimenti ai media, etichette degli inserzionisti e date di visualizzazione nei record restituiti.
  • Coda per le ricerche di dettaglio: Raccogli ID degli annunci pubblici e riferimenti alla fonte per esaminare record selezionati con l’endpoint di dettaglio.

Consigli degli esperti per la TikTok Ad Library Search API

  • Usa un nome di inserzionista specifico o una frase distintiva, perché la corrispondenza e l’ordinamento a monte determinano la pertinenza.
  • Scegli results_limit a multipli di 12 record; 2.000 rientra nel massimo generale ma non rispetta la regola del multiplo di 12.
  • Aspettati meno record di quelli richiesti quando la fonte termina, restituisce una pagina vuota o ripete un cursore.
  • Non dare per scontata la deduplicazione tra pagine; usa l’id stabile dell’annuncio nella tua pipeline quando l’unicità è importante.
  • Considera il pubblico stimato o le impression secondo la definizione della fonte, non come conversioni o prestazioni verificate.
  • Usa l’endpoint Ad Details per un singolo record selezionato; Search non offre l’arricchimento facoltativo dei dettagli.

Oltre alla TikTok Ad Library Search API, usa queste API quando ti serve un altro tipo di dati pubblici di TikTok Ad Library.

  • TikTok Ad Library Ad API — Trasforma l’URL di un annuncio TikTok pubblico noto in campi normalizzati di creatività, inserzionista, diffusione, destinazione, impression, media, pubblicazione e raccolta.

Esplora altre piattaforme

Combina i dati di TikTok Ad Library con i dati pubblici delle altre piattaforme social supportate.

TikTok Ad Library Search API — FAQ

TikTok Ad Library Search API è un’interfaccia programmatica per trovare i record pubblicitari pubblici supportati di TikTok con una sola query per nome dell’inserzionista o parola chiave e restituire riepiloghi normalizzati degli annunci fino a un limite allineato alle pagine.

query è una stringa obbligatoria e non vuota. Può essere un nome di inserzionista, un termine di brand o una parola chiave, ma l’endpoint non accetta più valori di query in una singola richiesta.

Il valore predefinito è 12. I valori devono essere numeri interi da 12 a 2.000 e multipli di 12, quindi 1.992 è il limite valido più alto.

No. La specifica SocQ attuale accetta solo query e results_limit; corrispondenza, ordinamento, area geografica e idoneità della fonte restano controllati a monte.

La raccolta si ferma al limite richiesto o quando la fonte non restituisce annunci, indica l’ultima pagina, omette un cursore o ne ripete uno. Anche le regole di visibilità e geografiche possono influire sulla disponibilità.

Il collettore evita i cicli di cursori ma non promette la deduplicazione dei record tra le pagine. Se serve, deduplica a valle in base a un id annuncio non null.

Ogni record di annuncio restituito costa 0,5 crediti SocQ, senza costo base. La stima predefinita copre 12 risultati e un risultato vuoto non comporta alcun addebito.