TikTokScrapingTutorial sulle API

Come estrarre video, profili e commenti di TikTok con un’API

Raccogli profili, video, commenti, ricerche e hashtag pubblici di TikTok con endpoint asincroni, pulizia degli input e JSON normalizzato.

SocQAggiornato il 10 settembre 202611 min di lettura

Una pagina pubblica di TikTok sembra semplice: un nome utente, un video, un thread di commenti. La specifica di raccolta non lo è. I profili non sono un feed di video. I commenti non sono un albero completo di risposte. La ricerca riguarda solo i video. La consultazione di una diretta non permette di scoprire le dirette.

Questo tutorial costruisce un flusso di lavoro manutenibile per i dati pubblici con le API di TikTok di SocQ. Copre la scelta dell’endpoint, la pulizia degli input, le attività asincrone, i record normalizzati, la cadenza di aggiornamento e l’uso responsabile.

SocQ TikTok API

Risposta rapida: instrada ogni input pubblico a POST /v1/tiktok/{resource}, salva l’ID dell’attività restituito e interroga /v1/tasks/{id} fino al completamento. Non inviare un nome utente di profilo all’endpoint dei video e non trattare un campo pubblico mancante come zero.

API ufficiale di TikTok o API di dati pubblici?

I prodotti ufficiali TikTok Research, Display e Content Posting sono la scelta giusta quando hai un’applicazione di ricerca approvata, un flusso di lavoro per creator o inserzionisti autorizzato tramite login, oppure la necessità di pubblicare. Questi prodotti prevedono la revisione dell’applicazione, OAuth e scope contrattuali. Non sono uno scraping generico di video pubblici qualsiasi.

Gli endpoint SocQ di questo tutorial accettano nomi utente, URL di video, query o hashtag pubblici noti ed eseguono una raccolta in sola lettura. Non si autenticano come utente TikTok, non concedono diritti di riutilizzo dei media restituiti e non sostituiscono i prodotti ufficiali di pubblicazione e ricerca. Scegli prima il modello di accesso: API ufficiali per il lavoro autorizzato o approvato, un’API di dati pubblici supportata per letture pubbliche con ambito ristretto.

Gli elenchi di prodotti in vendita si trovano su un’altra superficie. Per la ricerca di prodotti e le recensioni usa le API di TikTok Shop, non gli endpoint social qui sotto.

Scegliere l’endpoint TikTok corretto

SocQ espone attualmente dodici risorse TikTok. Questo tutorial si concentra sui sei lavori di raccolta più comuni. Le altre esistono e vanno instradate in modo esplicito quando ti servono.

RisorsaEndpointInput pubblico accettatoUso tipico
Profili/v1/tiktok/profilesNomi utente, con o senza @Identità, bio, conteggi visibili
Video/v1/tiktok/videosURL diretti dei videoUn video noto e le sue metriche
Video di un utente/v1/tiktok/user-videosNomi utenteUna finestra del feed pubblico di un creator
Commenti/v1/tiktok/commentsURL dei videoSolo commenti di primo livello
Ricerca/v1/tiktok/searchQueryScoperta solo di video
Hashtag/v1/tiktok/hashtagsTag, con o senza #Finestre di video per hashtag

Sono disponibili anche questi, facili da usare male se si procede per tentativi:

Sono operazioni di lettura pubblica. Confronta i modelli dei provider in API di scraping per TikTok e alternative alle API di TikTok quando il compito è la scelta del fornitore e non l’implementazione.

Normalizzare gli input prima di spendere una richiesta

Conserva l’input grezzo come provenienza, poi canonicalizza una copia:

  1. Rimuovi la @ iniziale dai nomi utente e il # iniziale dagli hashtag, oppure mantienili: entrambe le forme sono accettate, ma il tuo registro dovrebbe usare un’unica forma canonica.
  2. Elimina gli spazi superflui e rifiuta i valori vuoti.
  3. Converti gli URL dei profili in nomi utente nel tuo livello di input. Converti gli host di condivisione e mobile in un URL www.tiktok.com/@user/video/{id} quando l’ID del video è presente.
  4. Deduplica i nomi utente senza distinguere maiuscole e minuscole e gli URL per percorso canonico.
  5. Instrada per tipo di entità. Un nome utente non è l’URL di un video. Un hashtag non è una query di ricerca.
  6. Considera results_limit un tetto della richiesta, non una garanzia di completezza.

user-videos accetta results_limit da 20 a 2.000, sort_by con valore latest o popular e un region facoltativo. La ricerca riguarda solo i video e accetta sort_by con valore relevance, date o likes, più published_within con valore day, week, month, three_months o six_months.

Inviare un’attività di raccolta

Raccogliere profili pubblici:

curl -X POST "https://api.socq.ai/v1/tiktok/profiles" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"usernames":["tiktok","@natgeo"]}'

Raccogliere video noti:

curl -X POST "https://api.socq.ai/v1/tiktok/videos" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://www.tiktok.com/@tiktok/video/7234567890123456789"]}'

Raccogliere una finestra del feed di un creator:

curl -X POST "https://api.socq.ai/v1/tiktok/user-videos" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"usernames":["@tiktok"],"results_limit":20,"sort_by":"latest","region":"US"}'

Raccogliere i commenti di primo livello e, solo se hai già l’ID di un commento, le relative risposte:

curl -X POST "https://api.socq.ai/v1/tiktok/comments" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://www.tiktok.com/@tiktok/video/7234567890123456789"],"results_limit":100}'
curl -X POST "https://api.socq.ai/v1/tiktok/comment-replies" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.tiktok.com/@scout2015/video/6718335390845095173","comment_id":"6718335906996502534","results_limit":20}'

La scoperta tramite ricerca e hashtag usa la stessa autenticazione e lo stesso involucro dell’attività:

curl -X POST "https://api.socq.ai/v1/tiktok/search" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"python tutorial","results_limit":50,"sort_by":"relevance","published_within":"month"}'

La risposta crea un’attività asincrona. Salva il suo ID accanto all’ID del batch interno e agli input.

Interrogare lo stato dell’attività senza creare duplicati

curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=100" \
  -H "Authorization: Bearer $SOCQ_API_KEY"

Considera queued e running come stati attesi. Interroga con un backoff esponenziale e un ritardo massimo. Per un’attività riuscita, elabora data.results.items; quando has_more è true, continua con next_cursor.

La tabella dei job dovrebbe registrare:

  • ID del batch interno e ID dell’attività SocQ.
  • Tipo di risorsa e input canonici.
  • Timestamp di invio, dell’ultima interrogazione e di completamento.
  • Stato finale e categoria dell’errore normalizzata.
  • Ultimo cursore dei risultati salvato.

Non reinviare solo perché un worker si è riavviato. Riparti prima dallo stato dell’attività salvato.

Capire i campi restituiti

Tutti i record condividono campi di identità normalizzati come id, platform, resource, type, url, created_at, collected_at e extra. I campi specifici di ogni risorsa restano espliciti.

Un profilo include username, name, description, avatar_url, is_verified, is_private e metriche visibili. Non è un elenco dei video di quel creator.

Un video include caption, author, metriche visibili di riproduzioni, like, commenti e condivisioni, media, duration_seconds, hashtags, mentions e music quando sono pubblici. Gli URL dei media sono riferimenti alla fonte, non download permanenti.

Un commento include text, author, metrics.likes_count e spesso metrics.replies_count. I conteggi delle risposte non sono il testo delle risposte. I corpi delle risposte richiedono comment-replies e un comment_id dello stesso video.

I risultati di ricerca e hashtag riutilizzano la struttura del video. Sono risultati di scoperta ordinati per rilevanza o per finestra temporale, non un archivio esaustivo.

I dati mancanti devono restare null o assenti. Un conteggio di riproduzioni nascosto non è zero. Una trascrizione non disponibile non è una stringa vuota che puoi trattare come “nessun parlato”.

Worker Python per input TikTok misti

import time
import requests

BASE = "https://api.socq.ai/v1"
HEADERS = {
    "Authorization": f"Bearer {SOCQ_API_KEY}",
    "Content-Type": "application/json",
}

def collect(resource, payload):
    created = requests.post(
        f"{BASE}/tiktok/{resource}",
        headers=HEADERS,
        json=payload,
        timeout=30,
    )
    created.raise_for_status()
    task_id = created.json()["data"]["task_id"]

    delay = 2
    while True:
        response = requests.get(
            f"{BASE}/tasks/{task_id}",
            headers=HEADERS,
            timeout=30,
        )
        response.raise_for_status()
        task = response.json()["data"]

        if task["status"] == "succeeded":
            return task["results"]["items"]
        if task["status"] in {"failed", "cancelled"}:
            raise RuntimeError(task)

        time.sleep(delay)
        delay = min(delay * 1.5, 15)

profiles = collect("profiles", {"usernames": ["tiktok"]})
videos = collect("user-videos", {
    "usernames": ["tiktok"],
    "results_limit": 20,
    "sort_by": "latest",
})

In produzione, salva l’attività prima di interrogarne lo stato, pagina con next_cursor e riprova solo i guasti transitori.

Modellare separatamente entità e istantanee

I profili cambiano lentamente. Le metriche dei video e il volume dei commenti cambiano rapidamente.

tiktok_entity
  platform_id
  resource
  canonical_url_or_username
  stable public fields
  first_seen_at
  last_seen_at

tiktok_snapshot
  platform_id
  collected_at
  visible metrics
  mutable public fields
  source_task_id

Fai l’upsert dell’entità per resource + id quando esiste un ID. Usa come alternativa di riserva un URL canonico o un nome utente e conserva un percorso di unione per quando l’ID verrà scoperto. Aggiungi le istantanee solo dopo una raccolta riuscita e la convalida dello schema.

Non calcolare la crescita se in una delle due istantanee manca la metrica. Un conteggio nascosto non è zero.

Convalidare prima del caricamento in produzione

Come minimo, verifica che:

  • platform sia uguale a tiktok.
  • resource corrisponda all’endpoint usato.
  • I record dei profili non siano trattati come un feed di video.
  • I record dei commenti siano di primo livello, a meno che non provengano da comment-replies.
  • I risultati di ricerca siano video, non utenti o suoni.
  • I conteggi, quando presenti, non siano negativi.
  • created_at e collected_at siano interpretabili come timestamp.
  • Ogni record sia riconducibile a un input e a un’attività.

Metti in quarantena i record non validi invece di forzarne silenziosamente i tipi. Conserva la risposta grezza, l’errore di validazione e il momento della raccolta.

Scegliere la pianificazione di aggiornamento per entità

EntitàCadenza iniziale sensataMotivo
ProfiloSettimanale o mensileBio pubblica e campi di identità cambiano lentamente
Video notoDa oraria a giornaliera finché è attivoL’engagement si muove rapidamente dopo la pubblicazione
Finestra di video di un utenteGiornaliera per il monitoraggioI feed sono ordinati per rilevanza e incompleti
CommentiDa oraria a giornaliera finché il video è attivoI nuovi commenti di primo livello arrivano a ondate
Ricerca / hashtagGiornaliera o su richiestaClassifica e finestre cambiano
Follower / seguitiSettimanaleLe liste di relazioni sono grandi e parziali
DirettaSolo finché conosci già la stanzaL’endpoint non scopre le dirette

Usa le esigenze di business e la minimizzazione dei dati per ridurre la raccolta non necessaria.

Problemi più comuni

L’endpoint non restituisce alcun elemento

Verifica che il nome utente o l’URL sia pubblico, ancora disponibile e instradato alla risorsa corretta. Un video privato o eliminato deve restare un errore a livello di input, non diventare un profilo vuoto.

I profili sembrano “vuoti” di video

È previsto. profiles restituisce solo record di profilo. Usa user-videos per una finestra del feed.

I commenti hanno un conteggio di risposte ma non il testo delle risposte

L’endpoint dei commenti raccoglie i commenti di primo livello. Recupera il testo delle risposte con url più comment_id. L’endpoint delle risposte non scopre il comment_id partendo solo dall’URL del video.

La ricerca ha perso un suono o un utente

La ricerca riguarda solo i video. Non trattarla come una directory di utenti, suoni o LIVE.

Le metriche non corrispondono a quelle del browser

I conteggi sono istantanee del momento della raccolta e possono essere arrotondati, nascosti, in cache o aggiornati tra una richiesta e l’altra. Confronta timestamp e definizioni dei campi.

Gli URL dei media smettono di funzionare dopo un po’

Tratta gli URL di video, copertine e avatar come riferimenti temporanei alla fonte. Aggiornali solo quando il caso d’uso e i termini lo consentono.

Uso responsabile dei dati di TikTok

Raccogli solo i campi pubblici necessari per uno scopo legittimo. Non aggirare i muri di login, gli account privati, i limiti di età o le restrizioni tecniche. Evita deduzioni su aspetti sensibili e decisioni automatizzate che potrebbero incidere in modo significativo su una persona senza adeguate garanzie.

I dati di TikTok possono essere dati personali. Stabilisci una base giuridica dove richiesto, definisci procedure di conservazione ed eliminazione, proteggi le chiavi API e i record archiviati, rispetta i diritti applicabili e verifica i termini attuali di TikTok e la normativa locale con una consulenza legale qualificata. Un’API di dati pubblici non concede diritti aggiuntivi su musica, immagine delle persone o file video.

Lo stesso schema di catalogo è descritto nella guida alle API unificate per i social media, quando TikTok è una fonte tra tante.

Domande frequenti (FAQ)

Fare scraping di TikTok è legale?

Non esiste una risposta universale. Dipende da giurisdizione, dati, metodo di accesso, scopo, contratto e garanzie adottate. Questo tutorial non è una consulenza legale.

Le API ufficiali di TikTok sono gratuite?

L’accesso ufficiale a Research, Display e Content Posting è basato su richiesta o su permessi. Questo tutorial descrive un flusso di lettura pubblica e non sostituisce quei prodotti.

Posso estrarre video privati o eliminati?

No. Non aggirare i controlli di privacy o di accesso. Gli input privati ed eliminati devono fallire in modo pulito.

L’endpoint dei commenti restituisce il testo delle risposte?

No. Restituisce i commenti di primo livello. I conteggi delle risposte possono essere presenti. Il testo delle risposte richiede comment-replies e un comment_id.

Posso inviare l’URL di un profilo all’endpoint dei video?

No. L’endpoint dei video accetta URL diretti dei video. I profili e user-videos accettano nomi utente.

La ricerca restituisce utenti o suoni?

No. La ricerca attuale riguarda solo i video.

Quale chiave devo usare per la deduplicazione?

Preferisci resource + id; usa come alternativa di riserva un URL canonico normalizzato o un nome utente quando l’ID pubblico non è disponibile.

TIKTOK API

Prova il flusso di lavoro con un URL pubblico di TikTok

Invia input pubblici e ricevi record normalizzati con un contesto di origine tracciabile.

Scopri le API di TikTok