Come analizzare i temi dei creator TikTok: una pipeline pratica in Python

Quando un team cerca un argomento per la prossima campagna, consultare manualmente decine di profili si trasforma presto in una raccolta di appunti senza un metodo uniforme. Un analista annota le visualizzazioni, un altro le didascalie dei video, mentre post con formulazioni simili finiscono in fogli diversi. Dopo una settimana è difficile capire che cosa ricorre più spesso: un tema, un formato di presentazione o semplicemente un video di successo.

Un approccio pratico consiste nel tenere un piccolo elenco di account pubblici, recuperare regolarmente informazioni strutturate sui loro video e salvare ogni raccolta come uno snapshot separato. In seguito è possibile confrontare i post e le metriche disponibili nel tempo, usando un modello linguistico per raggruppare preliminarmente le didascalie. Ecco uno schema per una pipeline di ricerca in Python con TikTok Scraper API di jsonscraper.

Definisci la domanda prima di raccogliere i dati

Immaginiamo un team marketing di un piccolo marchio di integratori sportivi. Vuole scoprire quali temi ricorrono tra alcuni creator TikTok pubblici e quali video vale la pena esaminare manualmente. L’obiettivo è confrontare i post di account scelti in anticipo durante un periodo di osservazione, non creare una classifica universale della popolarità su TikTok.

Questo delimita l’analisi. Raccogliere i feed dei profili selezionati aiuta a studiare i contenuti e la frequenza di pubblicazione di quegli account. I contatori pubblici disponibili si possono registrare al momento della richiesta. Per valutare i risultati della propria pubblicità servono dati distinti, per esempio le spese e le conversioni provenienti dalla piattaforma pubblicitaria o dagli strumenti di analisi web.

Prima di collegare l’API, definisci il protocollo di ricerca: elenco degli account, data d’inizio, frequenza di raccolta, campi da analizzare e criteri d’inclusione dei post. Registra l’ora di ogni richiesta. In questo modo sarà possibile distinguere la variazione di una metrica relativa a un singolo video dalle differenze tra due serie di osservazioni.

Che cosa raccogliere e calcolare

Un piccolo progetto richiede tre livelli di dati. Il primo è l’identificativo dell’account con l’ora di avvio della raccolta. Il secondo è la risposta API originale, conservata per poterla verificare in seguito. Il terzo comprende i campi normalizzati da usare nelle interrogazioni e nei rapporti: ID del video, didascalia, ora di pubblicazione e contatori di interazione disponibili.

È necessario determinare i nomi dei campi e la struttura annidata a partire da un esempio dell’endpoint specifico. Non dare per scontato che l’elenco si chiami sempre videos o che il contatore delle visualizzazioni sia views. Esegui prima una richiesta documentata e controlla il JSON effettivo; poi configura la trasformazione nello schema scelto.

Tra gli indicatori utili ci sono il numero di nuovi post in un intervallo, la distribuzione dei post per tema e la variazione dei contatori pubblici tra gli snapshot dello stesso video. Per quest’ultimo confronto, abbina i record usando l’ID del video. In questo modo l’andamento di un video già pubblicato resta distinto dalle metriche dei nuovi post.

Collegare TikTok Scraper API

La descrizione di TikTok Scraper API indica l’indirizzo di base https://tiktok.evelode.com; la documentazione degli endpoint conferma GET /getUserFeed e i parametri query, max_cursor, count, region, with_pinned_posts, sort_type e cache_timeout. Per la prima richiesta basta indicare il profilo in query e, per esempio, il numero di elementi tramite count. La chiave license_key va passata nella query string; la relativa configurazione è descritta anche nella documentazione dell’API. Nella raccolta Postman puoi verificare l’endpoint e controllare la risposta prima dell’integrazione.

Conserva la chiave in una variabile d’ambiente. Non inserirla nel codice sorgente, in un repository, in un foglio di calcolo o in un’applicazione client. Esegui la richiesta, salva un esempio JSON valido con la data e il nome dell’endpoint e usalo come base per l’adattatore di normalizzazione e per i test.

Una richiesta minima in Python

La documentazione specifica che la risposta del feed utente contiene uno stato esterno e un oggetto tiktok, nel quale l’elenco dei post si trova in aweme_list. I record possono includere ID, didascalia, ora di pubblicazione, autore e statistiche. Controlla i campi e i valori effettivi nella risposta ricevuta: alcuni dati potrebbero non essere presenti.

import json
import os
from datetime import datetime, timezone
from pathlib import Path

import requests

API_KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
ENDPOINT_URL = "https://tiktok.evelode.com/getUserFeed"


def fetch_user_feed(handle: str, count: int = 20) -> dict:
    response = requests.get(
        ENDPOINT_URL,
        params={
            "license_key": API_KEY,
            "query": handle,
            "count": count,
            "region": "US",
        },
        timeout=45,
    )
    response.raise_for_status()
    payload = response.json()
    if not isinstance(payload, dict):
        raise ValueError("Era atteso un oggetto JSON")
    if payload.get("status") != "ok":
        raise RuntimeError(f"L'API ha restituito lo stato: {payload.get('status')!r}")
    tiktok = payload.get("tiktok")
    if not isinstance(tiktok, dict):
        raise ValueError("Nella risposta manca l'oggetto tiktok")
    return payload


def save_raw(payload: dict, account: str, output_dir: str = "data/raw") -> Path:
    collected_at = datetime.now(timezone.utc).isoformat()
    safe_account = "".join(c for c in account if c.isalnum() or c in "-_@")
    path = Path(output_dir) / f"{safe_account}_{collected_at.replace(':', '-')}.json"
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_text(
        json.dumps(
            {"collected_at": collected_at, "account": account, "payload": payload},
            ensure_ascii=False,
            indent=2,
        ),
        encoding="utf-8",
    )
    return path


def normalize_items(payload: dict, account: str, collected_at: str) -> list:
    items = payload["tiktok"].get("aweme_list", [])
    if not isinstance(items, list):
        raise ValueError("Il campo tiktok.aweme_list non è un elenco")

    observations = []
    for item in items:
        if not isinstance(item, dict):
            continue
        stats = item.get("statistics")
        stats = stats if isinstance(stats, dict) else {}
        author = item.get("author")
        author = author if isinstance(author, dict) else {}
        observations.append({
            "account_handle": account,
            "collected_at": collected_at,
            "video_id": item.get("aweme_id"),
            "caption": item.get("desc"),
            "published_at_epoch": item.get("create_time"),
            "author_handle": author.get("unique_id"),
            "views": stats.get("play_count"),
            "likes": stats.get("digg_count"),
            "comments": stats.get("comment_count"),
            "shares": stats.get("share_count"),
        })
    return observations


if __name__ == "__main__":
    account = "creator_handle"
    payload = fetch_user_feed(account, count=20)
    collected_at = datetime.now(timezone.utc).isoformat()
    raw_path = save_raw(payload, account)
    observations = normalize_items(payload, account, collected_at)
    print(f"Salvato: {raw_path}; record: {len(observations)}")

Prima di avviare il programma, imposta JSONSCRAPER_TIKTOK_LICENSE_KEY nell’ambiente e installa la libreria requests. Il codice controlla la risposta HTTP, lo stato esterno e la presenza dell’oggetto tiktok, quindi legge aweme_list. Salva il JSON originale ed estrae i campi confermati dalla documentazione, lasciando vuoti i valori mancanti. Il feed ottenuto è l’insieme dei risultati restituiti dall’API; perciò il rapporto dovrebbe indicare l’ora della richiesta e il profilo selezionato.

Conserva gli snapshot e confronta i post

Per un progetto di piccole dimensioni possono bastare SQLite o PostgreSQL. Conserva la risposta originale separatamente dai record normalizzati. Per la tabella delle osservazioni puoi usare uno schema come questo:

CREATE TABLE IF NOT EXISTS video_observations (
    account_handle TEXT NOT NULL,
    video_id TEXT NOT NULL,
    collected_at TEXT NOT NULL,
    published_at_epoch INTEGER,
    caption TEXT,
    views INTEGER,
    likes INTEGER,
    comments INTEGER,
    shares INTEGER,
    raw_file TEXT,
    PRIMARY KEY (account_handle, video_id, collected_at)
);

Ogni esecuzione aggiunge un nuovo snapshot invece di sovrascrivere quello precedente. Quando confronti i contatori, calcola la differenza solo se sono disponibili entrambi i valori dello stesso video. Includi nel rapporto l’intervallo tra le richieste e l’ora di osservazione: chiariscono il periodo in cui si è accumulata la variazione.

Per raggruppare i temi, comincia con un piccolo dizionario di categorie, poi aggiungi un classificatore o un modello linguistico se necessario. Fornisci al modello didascalie ripulite, ID dei post e categorie definite in anticipo. Un risultato strutturato con categoria e breve motivazione è più facile da confrontare tra un’esecuzione e l’altra di una descrizione libera.

Aggiungi un modello linguistico con etichette verificabili

Il modello può assegnare preliminarmente le didascalie a temi come «ricette», «allenamenti», «recensioni di prodotti» e «storie personali». Per iniziare, etichetta manualmente alcune decine di post. Confronta le etichette automatiche con questi esempi, affina le definizioni delle categorie e ripeti la valutazione dopo aver modificato il prompt o il modello.

È più affidabile calcolare con il normale codice il numero di nuovi post, la mediana dei contatori e la differenza tra gli snapshot. Usa il modello per classificare i testi e preparare brevi spiegazioni. Mantieni disponibili le didascalie originali e le osservazioni numeriche, così da poterle verificare.

Conserva insieme all’etichetta l’ID del post, la versione del prompt, la data di elaborazione e il modello utilizzato. Se la classificazione è errata, l’analista potrà trovare la didascalia e correggere la regola. È utile conservare separatamente l’etichetta iniziale e la correzione manuale.

Automatizza l’esecuzione

Dopo aver verificato un’esecuzione manuale, trasferisci lo script in cron, GitHub Actions, n8n o Make. Lo scheduler avvia la raccolta secondo una pianificazione, passa l’elenco degli account, registra il risultato e invia il rapporto al sistema di archiviazione scelto. Conserva la chiave nei segreti dell’ambiente di esecuzione. Prova prima il processo con un solo account, poi amplia l’elenco.

Suddividi l’automazione in fasi: coda degli account, chiamata API, salvataggio della risposta originale, normalizzazione, registrazione dello snapshot e preparazione del rapporto. Un errore relativo a un account non dovrebbe cancellare i risultati degli altri. Puoi rendere idempotente una nuova esecuzione tramite un ID di esecuzione e vincoli di unicità nel database.

Registra ora, account, endpoint, stato HTTP, durata, numero di elementi elaborati e descrizione dell’errore. Non inserire la chiave API nei log. Il parametro cache_timeout è indicato per /getUserFeed; puoi aggiungerlo alla richiesta se vuoi impostare un periodo di cache specifico. Nella documentazione dell’API, il valore predefinito è descritto come 3600 secondi.

Verifica la qualità prima di pubblicare il rapporto

Confronta alcuni record normalizzati con il JSON originale. Controlla che una raccolta ripetuta riconosca lo stesso video tramite il suo ID, che le date vengano interpretate come previsto, che i campi numerici abbiano il tipo giusto e che la quota di valori mancanti sia nota. Poi esegui di nuovo il processo e verifica che il database abbia mantenuto le vecchie osservazioni e aggiunto quelle nuove.

Non mescolare account e periodi di raccolta diversi. Per confrontare i temi, usa periodi della stessa durata oppure indica chiaramente la durata nel rapporto. Per analizzare l’andamento dei contatori, registra l’intervallo tra gli snapshot affinché il lettore possa capire l’ampiezza dei periodi a confronto.

Conserva il testo originale della didascalia e crea a parte una versione ripulita. Emoji, hashtag, link e caratteristiche linguistiche possono influenzare la classificazione; campi distinti permettono di verificare l’effetto della pulizia e ricalcolare le categorie senza interrogare nuovamente l’API.

Quali risultati offre la pipeline

Dopo alcuni cicli, il team avrà una tabella di post e snapshot, un raggruppamento preliminare delle didascalie per tema e un rapporto sui nuovi video del periodo selezionato. Questo aiuta a individuare i video da sottoporre a un esame esperto, a rilevare temi ricorrenti negli account selezionati e a verificare le variazioni dei contatori pubblici tra le date di osservazione.

Questi dati possono aiutare a formulare ipotesi per il calendario editoriale: confrontare diversi modi di presentare la stessa domanda oppure individuare temi da testare nei propri contenuti. Per valutare l’effetto commerciale, confronta le osservazioni con i dati interni delle campagne.

Per iniziare, scegli un piccolo elenco di account pubblici e verifica GET /getUserFeed nella raccolta di richieste Postman. Nel codice inserisci soltanto parametri e percorsi dei campi confermati dalla documentazione dell’endpoint e dalla risposta effettiva.

Raccolta responsabile dei dati pubblici

Limita l’elenco degli account all’obiettivo della ricerca, raccogli solo i campi necessari e stabilisci per quanto tempo conservare la risposta originale. Prima di utilizzare commercialmente i dati, verifica le condizioni applicabili della piattaforma e i requisiti in materia di dati personali nella tua giurisdizione. Il controllo degli accessi e l’eliminazione degli snapshot obsoleti aiutano a mantenere il processo entro i limiti del progetto.

Prima di inviare dati a un servizio di IA, rimuovi i campi di cui il modello non ha bisogno. Nel rapporto indica l’ID del post e la data di osservazione, così che un collaboratore possa aprire il record e verificare su quali elementi si basa la conclusione.

Breve checklist di avvio

1. Definisci la nicchia, l’elenco degli account, il periodo e le domande dell’analisi.
2. Controlla i parametri di GET /getUserFeed nella documentazione e la risposta effettiva in Postman.
3. Salva un esempio JSON e configura il normalizzatore sui campi confermati.
4. Registra la risposta originale e snapshot separati con l’ora di raccolta.
5. Calcola gli indicatori numerici con il codice; usa l’IA per raggruppare preliminarmente i testi.
6. Aggiungi pianificazione, logging, gestione dei tentativi e un periodo di conservazione.

Così il monitoraggio diventa uno studio riproducibile: ogni conclusione è collegata a un post e all’ora di osservazione, mentre il codice si basa sulla struttura effettiva dell’endpoint selezionato.