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
| Parametri | Obbligatorio | Descrizione |
|---|---|---|
query | Obbligatorio | Nome di inserzionista o parola chiave obbligatorio e non vuoto. Viene accettata esattamente una query. |
results_limit | Facoltativo | Limite 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.
- Scegli un solo nome di inserzionista o una sola parola chiave; l’endpoint non accetta un elenco di query.
- Invia con POST query e un results_limit facoltativo a /v1/tiktok-ad-library/search.
- Interroga /v1/tasks/{task_id} finché l’attività non raggiunge uno stato finale.
- 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.itemsCasi 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.
API correlate
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.