tiktok/
top-search

Cerca video e caroselli di foto di TikTok per parola chiave, con didascalie, dettagli dei creator, link ai media e conteggi di engagement restituiti insieme in un unico elenco JSON.

TikTok Top Search API

Video e caroselli di foto
Ricerca per parola chiave
Filtri di ordinamento e di pubblicazione
0,7 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 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

ParametriObbligatorioDescrizione
queryObbligatorioParola 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_byFacoltativoOrdinamento 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_withinFacoltativoIntervallo 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.
regionFacoltativoCodice 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_limitFacoltativoNumero 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.

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.

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.

Esplora altre piattaforme

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

TikTok Top Search API — FAQ

TikTok Top Search API è un’interfaccia programmatica per trovare i video e i caroselli di foto pubblici di TikTok a partire da una parola chiave o da una frase. Restituisce didascalie, creator, link ai media e conteggi di interazione, con ordinamento e filtri sul periodo di pubblicazione facoltativi.

È un post di immagini di TikTok che contiene più foto da scorrere. Nei risultati, type=photo_carousel identifica quel formato e media contiene le voci delle immagini.

TikTok Search restituisce solo video, mentre Top Search può includere sia video sia caroselli di foto. Scegli in base al fatto che la tua raccolta o la tua visualizzazione debba gestire anche i post di immagini.

Non esiste un filtro di input solo per le foto. Dopo il recupero, seleziona i record il cui type è photo_carousel; il limite di risultati si applica prima del tuo filtro sul formato, quindi il numero di foto rimaste può essere inferiore.

No. region cambia la disponibilità dei contenuti per la ricerca, non l’origine geografica di ogni risultato; non usarlo come sostituto di un campo con la posizione del creator o del post.

No. results_limit è un tetto sulla selezione restituita, non una garanzia che ogni post di TikTok corrispondente venga incluso. Una ricerca può restituire meno record del limite richiesto.

Ogni record di contenuto restituito costa 0,7 crediti, che sia un video o un carosello di foto. Non c’è alcun costo di base; un limite di 100 stima 70 crediti, mentre 20 record restituiti costano 14 crediti.