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.

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.
| Risorsa | Endpoint | Input pubblico accettato | Uso tipico |
|---|---|---|---|
| Profili | /v1/tiktok/profiles | Nomi utente, con o senza @ | Identità, bio, conteggi visibili |
| Video | /v1/tiktok/videos | URL diretti dei video | Un video noto e le sue metriche |
| Video di un utente | /v1/tiktok/user-videos | Nomi utente | Una finestra del feed pubblico di un creator |
| Commenti | /v1/tiktok/comments | URL dei video | Solo commenti di primo livello |
| Ricerca | /v1/tiktok/search | Query | Scoperta solo di video |
| Hashtag | /v1/tiktok/hashtags | Tag, con o senza # | Finestre di video per hashtag |
Sono disponibili anche questi, facili da usare male se si procede per tentativi:
video-transcriptper URL di video pubblici risolvibili.comment-repliesper un URL di video più uncomment_idnoto.trending-feedper unregionobbligatorio.followers-listefollowing-listper nomi utente pubblici.live-room-infoper unroom_ide unouser_idnoti. Non scopre le dirette e non attende che un account vada in diretta.
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:
- 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. - Elimina gli spazi superflui e rifiuta i valori vuoti.
- 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. - Deduplica i nomi utente senza distinguere maiuscole e minuscole e gli URL per percorso canonico.
- Instrada per tipo di entità. Un nome utente non è l’URL di un video. Un hashtag non è una query di ricerca.
- Considera
results_limitun 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:
platformsia uguale atiktok.resourcecorrisponda 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_atecollected_atsiano 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 sensata | Motivo |
|---|---|---|
| Profilo | Settimanale o mensile | Bio pubblica e campi di identità cambiano lentamente |
| Video noto | Da oraria a giornaliera finché è attivo | L’engagement si muove rapidamente dopo la pubblicazione |
| Finestra di video di un utente | Giornaliera per il monitoraggio | I feed sono ordinati per rilevanza e incompleti |
| Commenti | Da oraria a giornaliera finché il video è attivo | I nuovi commenti di primo livello arrivano a ondate |
| Ricerca / hashtag | Giornaliera o su richiesta | Classifica e finestre cambiano |
| Follower / seguiti | Settimanale | Le liste di relazioni sono grandi e parziali |
| Diretta | Solo finché conosci già la stanza | L’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