Come valutare la coerenza tematica di un creator TikTok attraverso i post pubblici

Un creator può sembrare adatto a una campagna guardando il profilo e alcuni video riusciti, ma il feed più recente racconta una storia più importante: continua a parlare regolarmente del tema che interessa? Una verifica manuale diventa rapidamente obsoleta e una singola occhiata rischia di ridursi alla selezione dei post più in vista. Per un’agenzia o un brand è più utile raccogliere un campione ripetibile di video pubblici, salvare lo stato alla data della verifica e valutare la pertinenza tematica con criteri uniformi.

Di seguito è descritto un processo pratico per valutare il feed pubblico di un creator TikTok. Utilizza TikTok Scraper API di jsonscraper e Python: recupera i post tramite un endpoint documentato, salva il JSON originale, trasforma i campi verificati in una tabella e calcola la percentuale di video pertinenti a un tema definito. Facoltativamente, le descrizioni possono essere passate a un classificatore testuale in una fase successiva, controllata separatamente.

Per prima cosa, definite cosa significa «pertinente»

Supponiamo che un team stia selezionando un creator per una campagna sul caffè preparato in casa. Il numero di follower e la popolarità di singoli video possono aiutare a descrivere la copertura, ma da soli non dicono quanto il feed sia legato al caffè. Per un primo filtro servono segnali relativi ai contenuti: la descrizione del video menziona la preparazione del caffè, le attrezzature, le ricette o le recensioni? Quanti post sul tema sono compresi nell’intervallo di osservazione stabilito? Qual è la percentuale di video pertinenti fra quelli raccolti?

Prima di raccogliere i dati, annotate i criteri in un breve dizionario: per esempio «espresso», «macinacaffè», «latte», «infusione». Aggiungete eccezioni e parole ambigue. «Caffè» può comparire in una battuta, un’integrazione pubblicitaria o un contesto casuale; perciò, una corrispondenza automatica nel testo è una prima classificazione, non una valutazione definitiva del creator. Distinguete almeno tre categorie: corrispondenza evidente, possibile corrispondenza e video non pertinente.

Anche il campione va definito in anticipo. Per esempio, si possono analizzare gli ultimi 20 post ottenuti a ogni esecuzione settimanale. Questa è una regola del vostro monitoraggio, non una garanzia che l’API restituisca esattamente quel numero: disponibilità e composizione dei risultati dipendono dalla risposta a una specifica richiesta. Registrate l’ora di raccolta, il numero di elementi ottenuti e i parametri della richiesta, così da confrontare gli snapshot senza mescolare criteri diversi.

Richiedere il feed di un creator

Nella documentazione di jsonscraper, l’endpoint GET /getUserFeed accetta il parametro obbligatorio query, che può contenere il nome utente o l’URL del profilo. I parametri facoltativi indicati sono count, region, sort_type, with_pinned_posts e max_cursor. La chiave API viene trasmessa nel parametro license_key della query string: conservatela in una variabile d’ambiente e non nel codice sorgente. I dettagli degli endpoint e dei parametri sono disponibili nella documentazione ufficiale dell’API TikTok.

Nella risposta, controllate prima il campo esterno status, quindi accedete all’oggetto tiktok. Per il feed dell’utente, l’elenco dei post si trova in tiktok.aweme_list. Lo schema osservato include l’ID del video, il testo della descrizione, l’ora di pubblicazione, l’autore, l’URL e un oggetto con le statistiche. Alcuni campi potrebbero mancare: il programma di elaborazione deve conservarli come valori vuoti, senza sostituirli con numeri inventati.

Il seguente esempio minimale è pensato per Python 3.8+ e per la libreria requests. Salvate la chiave in JSONSCRAPER_TIKTOK_LICENSE_KEY. Il codice esegue una richiesta, controlla la risposta HTTP e lo stato esterno dell’API, salva il JSON originale e stampa le righe normalizzate.

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

import requests

API_KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
PROFILE = "creator_username"

params = {
    "license_key": API_KEY,
    "query": PROFILE,
    "count": 20,
    "region": "US",
    "sort_type": 0,
    "with_pinned_posts": 0,
}

response = requests.get(
    "https://tiktok.evelode.com/getUserFeed",
    params=params,
    timeout=30,
)
response.raise_for_status()
payload = response.json()

if payload.get("status") != "ok":
    raise RuntimeError("TikTok API returned a non-ok status")

tiktok = payload.get("tiktok") or {}
items = tiktok.get("aweme_list") or []

stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
Path("snapshots").mkdir(exist_ok=True)
Path(f"snapshots/{PROFILE}_{stamp}.json").write_text(
    json.dumps(payload, ensure_ascii=False, indent=2),
    encoding="utf-8",
)

rows = []
for item in items:
    stats = item.get("statistics") or {}
    author = item.get("author") or {}
    rows.append({
        "aweme_id": item.get("aweme_id"),
        "created_at": item.get("create_time"),
        "description": item.get("desc") or "",
        "share_url": item.get("share_url"),
        "creator": author.get("unique_id") or author.get("nickname"),
        "play_count": stats.get("play_count"),
        "digg_count": stats.get("digg_count"),
        "comment_count": stats.get("comment_count"),
        "share_count": stats.get("share_count"),
    })

print(json.dumps(rows, ensure_ascii=False, indent=2))

Per questo endpoint, sort_type è descritto come 0 per il feed più recente e 1 per quello più popolare. Nell’esempio è selezionata la modalità dei post recenti, mentre i video fissati sono esclusi con with_pinned_posts=0, così che un vecchio post fissato non entri nel campione delle nuove pubblicazioni. Se serve un’altra modalità, salvate il parametro nei metadati dello snapshot e applicatelo allo stesso modo a ogni esecuzione.

Elaborare la risposta: dal JSON a una tabella riproducibile

È utile salvare la risposta originale prima di trasformarla. In questo modo si può verificare la normalizzazione, capire perché una riga è rimasta vuota e adattare il programma se cambia la disponibilità dei campi facoltativi nelle risposte. Nell’archivio di lavoro, insieme al JSON, salvate l’ora di raccolta in UTC, il profilo richiesto, i parametri e la versione dello script. Non inserite la chiave API negli archivi o nei log.

Per le esecuzioni successive, usate aweme_id come identificativo del post, se presente. La deduplicazione tramite questo ID evita di conteggiare lo stesso video più volte quando viene recuperato di nuovo. Conservate però snapshot separati delle statistiche: visualizzazioni e interazioni si riferiscono al momento dell’osservazione, non sono caratteristiche immutabili del video. Se un campo statistico manca, lasciatelo vuoto ed escludete il record dal calcolo della metrica corrispondente.

Nello schema, l’ora di pubblicazione è indicata da create_time. Per la tabella analitica, convertitela in una data e conservate sia il valore originale sia l’ora normalizzata in UTC. Prima di procedere ai calcoli, controllate alcuni record reali della risposta ricevuta per verificare il tipo di dato e le unità previste. Questo controllo è particolarmente importante per i grafici temporali: un errore nella conversione dell’ora sposta i post da un giorno all’altro e altera il confronto settimanale.

Si può creare un classificatore tematico minimale senza un modello: normalizzare il testo, cercare le frasi definite e segnalare le corrispondenze. Per ottenere una classificazione più utile, preparate un insieme di descrizioni verificate manualmente e regole per i casi limite. Confrontate quindi un semplice filtro a dizionario con le annotazioni umane: individuate le espressioni che generano falsi positivi e aggiornate il dizionario. Si ottiene così una base chiara con cui valutare il successivo impiego dell’IA.

import re

KEYWORDS = (
    "caffè", "espresso", "macinacaffè", "latte", "infusione",
)


def normalize(text):
    text = (text or "").casefold()
    return re.sub(r"\s+", " ", text).strip()


def classify(description):
    text = normalize(description)
    matches = [word for word in KEYWORDS if word in text]
    return {
        "topic_match": bool(matches),
        "matched_terms": matches,
    }

for row in rows:
    row.update(classify(row["description"]))

Una parola chiave nella descrizione può essere un segnale utile, ma è preferibile che il classificatore restituisca una motivazione comprensibile: l’elenco dei termini trovati, non soltanto un’etichetta «sì/no». Per i modelli linguistici, usate una richiesta strutturata: passate la descrizione del video e categorie fisse, chiedendo di restituire la categoria, una breve motivazione e un livello di confidenza. Conservate separatamente il testo originale e la risposta del modello. Le decisioni che incidono sul budget o sulla scelta di un partner devono essere verificate da una persona tramite i link ai post.

Calcolate gli indicatori usando un denominatore chiaro

Per un rapporto semplice bastano la quota di video tematici e la frequenza delle pubblicazioni. La quota è il numero di video con corrispondenza tematica confermata diviso per il numero di video che è stato possibile classificare. Mostrate sempre entrambi i valori: per esempio «7 su 18 descrizioni verificate». Il risultato è così più comprensibile e si può notare se la percentuale deriva da un campione troppo piccolo.

La frequenza di pubblicazione si può esprimere come numero di video ottenuti in un periodo fisso, per esempio negli ultimi 30 giorni. Stabilite i limiti del periodo in base all’ora di raccolta e alle date di pubblicazione. Se create snapshot settimanali, conservate il risultato di ogni esecuzione e non soltanto una riga riepilogativa aggiornata: in questo modo si possono vedere i cambiamenti di argomenti e attività. Non interpretate il numero di elementi raccolti come un archivio completo dei post del creator: analizzate il campione effettivamente ottenuto e indicate chiaramente la regola usata per selezionarlo.

Visualizzazioni, like, commenti e condivisioni sono un contesto utile per ciascun video. Confrontare i valori assoluti richiede cautela: un post più vecchio potrebbe aver avuto più tempo per accumulare interazioni. Per confrontare i video dello stesso creator, registrate l’ora di ogni raccolta e osservate l’andamento dello stesso video tra snapshot successivi. Non definite la differenza tra due snapshot «velocità di crescita» se l’intervallo e la disponibilità delle misurazioni non sono stati registrati.

Una scheda riepilogativa utile per ogni profilo include la data di raccolta, i parametri scelti, il numero di post ottenuti, il numero di descrizioni classificate, il numero di corrispondenze tematiche, un elenco di URL di esempio e una breve nota sui casi ambigui. Questa tabella consente a un collega di verificare la conclusione e a un altro analista di ripetere il metodo sul profilo successivo.

Paginazione e pianificazione

Se il campione richiede un’altra pagina, la documentazione per il feed del profilo usa max_cursor, ottenuto dalla risposta precedente. Passatelo senza trasformarlo: il cursore è un valore opaco, da conservare e restituire all’API. Se intendete richiedere altre pagine, controllate anche has_more nella risposta. Impostate un numero massimo di pagine o un budget complessivo di richieste, così che la raccolta termini in modo prevedibile.

cursor = None
all_items = []
max_pages = 3

for _ in range(max_pages):
    page_params = dict(params)
    if cursor is not None:
        page_params["max_cursor"] = cursor

    page_response = requests.get(
        "https://tiktok.evelode.com/getUserFeed",
        params=page_params,
        timeout=30,
    )
    page_response.raise_for_status()
    page_payload = page_response.json()

    if page_payload.get("status") != "ok":
        raise RuntimeError("TikTok API returned a non-ok status")

    page = page_payload.get("tiktok") or {}
    all_items.extend(page.get("aweme_list") or [])

    if not page.get("has_more"):
        break

    cursor = page.get("max_cursor")
    if cursor is None:
        break

Scegliete la frequenza di esecuzione in base all’obiettivo: per una valutazione iniziale basta un’esecuzione manuale; per un elenco di creator, una pianificazione settimanale può rilevare i cambiamenti senza interrogare continuamente l’API. L’esecuzione può essere affidata a cron, a un’attività CI o a un orchestratore. Il flusso è semplice: recuperare i profili da una tabella, eseguire le richieste con un limite al parallelismo, salvare gli snapshot, controllare la percentuale di risposte riuscite e inviare il riepilogo a una tabella di lavoro. Dopo un errore temporaneo, ripetete la richiesta un numero limitato di volte con un intervallo di attesa; registrate separatamente gli errori delle richieste autenticate per verificare la chiave e la configurazione.

Quando usare l’IA e quando serve una verifica

L’IA è utile per classificare descrizioni che contengono gergo, più lingue o formulazioni senza parole chiave esatte. Per prima cosa definite un elenco chiuso di categorie e chiedete al modello di basarsi soltanto sul testo della descrizione. Poi misurate la qualità su un piccolo campione annotato manualmente: confrontate le categorie del modello con le decisioni di un revisore ed esaminate separatamente gli errori e i casi ambigui. Nel rapporto è meglio includere la percentuale di accordo tra modello e annotazione manuale e il numero di esempi verificati, anziché un punteggio complessivo difficile da interpretare.

Non affidate al modello il compito di «scegliere il creator migliore» senza criteri. Scomponete invece il processo in indicatori misurabili: quota tematica, regolarità, esempi di video pertinenti e intervallo delle reazioni pubbliche. Il modello può riassumere brevemente questi dati e indicare i link che supportano la valutazione; la decisione finale spetta al team, che tiene conto del formato della campagna, del pubblico e degli accordi con il creator.

Se l’analisi riguarda contenuti sponsorizzati, verificate separatamente, nei post stessi e alla luce delle norme applicabili, che i rapporti tra il creator e il brand siano dichiarati. La guida della Federal Trade Commission statunitense spiega che il legame con un brand deve essere comunicato in modo ben visibile accanto alla raccomandazione; una biografia del profilo o una parte nascosta del testo potrebbero non bastare a informare chiaramente il pubblico. Consultate le indicazioni FTC per i creator sui social media. Il monitoraggio dei dati pubblici aiuta a raccogliere elementi per la verifica, ma valutare il rispetto delle regole richiede il contesto del singolo post e della campagna.

Quale sarà il risultato

Una volta configurata la pipeline, il team ottiene snapshot datati del feed pubblico, una tabella dei post con descrizioni e metriche disponibili e un calcolo ripetibile della quota tematica. Questi dati permettono di selezionare più rapidamente i profili da verificare, notare i cambiamenti nei temi e documentare le ragioni della valutazione. Il metodo resta verificabile: JSON originale, parametri della richiesta, regole di classificazione e link ai video consentono di ricostruire il passaggio dai dati alla conclusione.

Per il primo test, eseguite lo script su un profilo, salvate la risposta grezza e verificate manualmente alcune classificazioni. Poi fissate il dizionario degli argomenti, le regole di campionamento e il formato del rapporto. Quando il risultato sarà riproducibile, aggiungete una pianificazione e una coda di profili. Per la descrizione degli endpoint e dei parametri consultate la documentazione dell’API; per una panoramica del prodotto e delle opzioni di integrazione disponibili, visitate la pagina TikTok Scraper API.

Checklist pratica prima dell’avvio

• Annotate il tema della campagna, i termini inclusi e alcuni esempi di casi limite.
• Definite l’intervallo del campione, il valore di count, l’ordinamento e l’impostazione dei post fissati.
• Conservate il JSON originale, la data di raccolta e i parametri separatamente dalla chiave segreta.
• Usate aweme_id per deduplicare, se l’identificativo è presente.
• Distinguete i valori mancanti dallo zero e non calcolate medie senza un criterio chiaro.
• Indicate la dimensione del campione accanto alla quota tematica e includete link di esempio.
• Verificate la classificazione dell’IA su un campione annotato manualmente prima di usarla per decisioni sulla campagna.
• Aggiornate la valutazione secondo una pianificazione e confrontate snapshot raccolti con le stesse regole.