TikTok Top Search
TikTok Top search riunisce video e caroselli di foto, cioè post composti da più immagini, intorno a una parola chiave o a una frase. Didascalie, identità dei creator, media e conteggi di interazione ti aiutano a confrontare come lo stesso tema compare in questi diversi formati di contenuto.
Funzionalità della TikTok Top Search API
- Trova video e post di immagini in un’unica ricercaLa stessa parola chiave può restituire post video e caroselli di foto, con il campo type che indica il formato, così puoi tenere entrambi in un unico dataset oppure separarli per la revisione.
- Scegli l’ordinamento e l’intervallo di pubblicazioneOrdina i contenuti trovati per pertinenza, data di pubblicazione o Mi piace e aggiungi un filtro sul periodo di pubblicazione per concentrare la selezione restituita sul tipo di contenuto che vuoi analizzare.
- Leggi il contenuto insieme al creator e ai contatoriOgni risultato riunisce didascalia, informazioni sul creator, link ai media e conteggi di interazione disponibili, così puoi collegare l’argomento e il formato di un post all’account che l’ha pubblicato.
Parametri della TikTok Top Search API
| Parametri | Obbligatorio | Descrizione |
|---|---|---|
query | Obbligatorio | Parola chiave o frase obbligatoria che descrive cosa vuoi trovare, per esempio coffee o home workout; inserisci un testo di ricerca e non l’URL di un post di TikTok. |
sort_by | Facoltativo | Ordinamento facoltativo: relevance mette per primi i risultati più pertinenti, date ordina per data di pubblicazione e likes ordina per numero di Mi piace; il valore predefinito è relevance. |
published_within | Facoltativo | Intervallo di pubblicazione facoltativo: day seleziona ieri, week questa settimana, month questo mese, three_months gli ultimi tre mesi e six_months gli ultimi sei mesi; lascialo vuoto per non applicare alcun filtro aggiuntivo sul periodo di pubblicazione. |
region | Facoltativo | Codice regione facoltativo di due lettere, come US o GB, che cambia quali contenuti sono accessibili per la ricerca; non dimostra che i post o i creator restituiti si trovino in quel paese. |
results_limit | Facoltativo | Numero massimo facoltativo di record di contenuto, da 1 a 2.000, con valore predefinito 100; video e caroselli di foto contano entrambi nel totale e possono essere restituiti meno risultati. |
Come usare la TikTok Top Search API
La richiesta avvia un’attività di raccolta in background, quindi la prima risposta contiene un ID attività e non i dati finali; usa quell’ID per controllare l’avanzamento e recuperare i risultati.
- Inserisci una parola chiave sull’argomento, scegli se è più utile la pertinenza, la data o i Mi piace e imposta un limite di risultati; aggiungi un intervallo di pubblicazione o una regione solo se ti servono queste opzioni.
- Prima di eseguire l’esempio, sostituisci $SOCQ_API_KEY con la tua chiave API oppure imposta quella variabile d’ambiente. Invia l’input JSON a POST /v1/tiktok/top-search con l’intestazione Authorization mostrata qui sotto, poi salva il task_id dalla risposta.
- Usa GET /v1/tasks/{task_id} con l’ID salvato per controllare l’avanzamento. queued significa in attesa, running significa raccolta in corso e retrying significa che è in corso un nuovo tentativo. Attendi succeeded prima di leggere i risultati; se l’attività è failed, leggi error_message per conoscere il motivo.
- Quando l’attività riesce, leggi data.results.items: ogni elemento di questo elenco descrive un post video o un carosello di foto. Un elenco vuoto significa che l’attività è terminata senza restituire alcun record.
- Se data.results.has_more è true, il valore next_cursor è il segnaposto per un’altra pagina di risultati salvati. Copialo senza modifiche nel parametro cursor di GET /v1/tasks/{task_id}?cursor=... e continua finché has_more è false.
curl -X POST "https://api.socq.ai/v1/tiktok/top-search" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"coffee","sort_by":"relevance","results_limit":20}'Casi d’uso della TikTok Top Search API
- Crea una raccolta di contenuti per argomento: Cerca un argomento come coffee, poi salva didascalie, handle dei creator, link e tipi di contenuto in una tabella di revisione con esempi sia di video sia di post di immagini.
- Confronta i conteggi di interazione dei post restituiti: Combina Mi piace, commenti e condivisioni disponibili con il formato e l’ora di pubblicazione di ogni post per preparare un foglio di confronto, conservando la query e i filtri per sapere come sono stati selezionati gli esempi.
Consigli degli esperti per la TikTok Top Search API
- Quando mostri un risultato, controlla prima type e media: photo_carousel indica un post di immagini e richiede una galleria di immagini al posto di un lettore video.
- Se raccogli più parole chiave, usa l’ID del post per deduplicare le corrispondenze ripetute e conserva la parola chiave associata a ogni raccolta, così lo stesso post non viene contato più volte per errore.
- Se il tuo flusso di lavoro accetta solo video, usa TikTok Search; se ti servono sia video sia post di immagini, mantieni Top Search e gestisci entrambi i formati nella visualizzazione.
- Se un risultato fotografico non ha durata o conteggio di riproduzioni, lascia vuota quella misura invece di interpretarla come un video di zero secondi o un post mai visualizzato.
API correlate
Oltre alla TikTok Top Search API, usa queste API quando ti serve un altro tipo di dati pubblici di TikTok.
- TikTok Profiles API — Recupera identità del profilo pubblico, bio, flag dell’account e conteggi del pubblico a partire dal nome utente.
- TikTok Hashtags API — Raccoglie video pubblici, creator, media, suoni ed engagement per gli hashtag indicati.
- TikTok Comments API — Raccoglie i commenti pubblici di primo livello, autori, engagement, menzioni e flag di interazione del creator.
- TikTok Videos API — Recupera creator, didascalia, media, musica, tag, menzioni ed engagement dagli URL dei video.
- TikTok Search API — Cerca video pubblici per parola chiave con ordinamento e filtri di pubblicazione supportati.
- TikTok Live Room Info API — Consulta una diretta nota tramite la coppia di ID della stanza e del proprietario, restituendo stato, contesto del proprietario, immagine di copertina e conteggi del pubblico.
- TikTok Comment Replies API
- TikTok Followers List API
- TikTok Following List API
- TikTok User Videos API
- TikTok Trending Feed API
- TikTok Video Transcript API
- TikTok Search Users API
- TikTok Song API
- TikTok Song Videos API
- TikTok Popular Songs API
- TikTok User Live API
- TikTok Audience Demographics API
- TikTok Similar Accounts API
- TikTok Reposts API
- TikTok Playlists API
- TikTok Hashtag Views API
- TikTok Sound Search API
- TikTok Live Search API
- TikTok Photo Search API
- TikTok Trending Searches API
- TikTok Creator Search Insights API
- TikTok Live Ranking API
- TikTok Live Shopping API
- TikTok Fake Views Checker API
- TikTok Comment Keywords API