Come confrontare i contenuti TikTok dei concorrenti con metriche pubbliche: una pipeline in Python

Due team pubblicano video su prodotti simili, ma li valutano manualmente secondo criteri diversi: uno si concentra sulle visualizzazioni, un altro sui commenti, mentre un terzo salva i link in una chat. Dopo una settimana è difficile capire quali formati si ripetano tra i concorrenti, quali pubblicazioni ottengano reazioni significative e cosa sia cambiato dall’ultima analisi.

La soluzione consiste nel raccogliere un campione limitato e riproducibile di video pubblici tramite parole chiave definite in anticipo, salvare il JSON originale e creare una tabella con campi uniformi. In questo modo è possibile confrontare i video con un unico flusso di lavoro, senza confondere osservazioni casuali con conclusioni sul mercato. Ecco uno schema per un semplice monitoraggio dei concorrenti in Python con TikTok Scraper API di jsonscraper.

Per prima cosa, definite la domanda dell’analisi

La raccolta dei dati è utile quando è già chiaro quale decisione verrà presa in base ai risultati. Per esempio, il team marketing di un produttore di borracce sportive vuole capire come i concorrenti presentano i propri prodotti nei video brevi: con una dimostrazione d’uso, un unboxing, un confronto o la reazione di un utente. Non serve copiare l’intero TikTok. Bastano alcune query mirate e un’osservazione ripetibile dei video restituiti dall’API per quelle query.

Formulate la domanda in modo che sia verificabile: «Quali formati di descrizione e dimostrazione ricorrono nei video pubblicati per le nostre cinque frasi chiave e quali video individuati hanno attualmente il maggior numero di visualizzazioni e reazioni?». Questa formulazione distingue due livelli di analisi. Il testo e la descrizione aiutano a raggruppare gli approcci creativi; i conteggi di visualizzazioni, Mi piace, commenti e condivisioni offrono un’istantanea delle reazioni pubbliche al momento della raccolta.

Questa istantanea è utile per stabilire le priorità della revisione manuale e monitorare i cambiamenti. Descrive i video restituiti per query, parametri e orario di esecuzione specifici. Perciò una conclusione corretta potrebbe essere «nel nostro campione ricorrono spesso gli unboxing» oppure «questo gruppo di video ha attualmente una mediana delle visualizzazioni più alta». È questa scala di analisi che aiuta il team a scegliere ipotesi da testare con i propri contenuti.

Progettate una pipeline di dati essenziale

Suddividete il lavoro in quattro fasi: raccolta, archiviazione della risposta grezza, normalizzazione e analisi. La raccolta interroga l’API per ogni parola chiave approvata. La risposta grezza viene salvata integralmente per poterla verificare in seguito. La normalizzazione trasforma la struttura JSON annidata in righe di una tabella; l’analisi calcola le metriche e raggruppa i video per parola chiave o per formato assegnato manualmente.

• Raccolta. Richiedete un numero definito di risultati per ciascuna parola chiave, usando la stessa area geografica e lo stesso ordinamento.
• Archivio. Registrate il JSON originale e l’orario di acquisizione, così da poter verificare i valori estratti.
• Normalizzazione. Conservate l’ID del video, il link, la descrizione, l’autore, l’orario di pubblicazione e i contatori disponibili.
• Controllo qualità. Rimuovete i duplicati in base all’ID, segnalate i valori mancanti e conservate la parola chiave che ha restituito il video.
• Confronto. Calcolate indicatori personalizzati solo a partire dai campi di origine disponibili e confrontate i gruppi all’interno della stessa istantanea.

Questo approccio è preferibile a un semplice elenco di link perché conserva la provenienza di ogni riga e permette di distinguere la ricomparsa dello stesso video da un nuovo contenuto. Memorizzate anche la data di raccolta: i contatori pubblici possono cambiare, quindi il valore restituito oggi non va considerato una caratteristica permanente del video.

Funzionalità di TikTok Scraper API

Per cercare video tramite una query testuale, la documentazione di jsonscraper descrive l’endpoint GET /searchVideo all’indirizzo di base https://tiktok.evelode.com. Il parametro obbligatorio è keyword; sono disponibili anche count, cursor, region, date_posted, sort_by e cache_timeout. La documentazione indica le opzioni di ordinamento most-liked, relevance e date-posted e, tra i periodi di pubblicazione, yesterday, this-week, this-month, last-3-months, last-6-months e all-time. Verificate i nomi e le funzioni dei parametri nel riferimento agli endpoint TikTok.

La chiave viene passata nel parametro di query license_key. Per uno script operativo, inseritela nella variabile d’ambiente JSONSCRAPER_TIKTOK_LICENSE_KEY, non in un file sorgente, in una tabella o nel log di esecuzione. Nella risposta, controllate il valore di primo livello status, quindi analizzate l’oggetto tiktok. Per la ricerca, la struttura può includere un elenco aweme_list e anche search_item_list, in cui i dettagli del video si trovano all’interno di aweme_info. Il codice seguente gestisce entrambe le forme.

Le risposte di ricerca verificate includono l’ID del video, la descrizione, l’orario di pubblicazione, il link, i dati dell’autore e metriche come visualizzazioni, Mi piace, commenti, salvataggi e condivisioni. Alcuni campi potrebbero mancare in singoli record. Nella tabella lasciate vuoti questi valori anziché sostituirli con zero: zero indica un valore misurato, mentre un campo vuoto indica che il valore non era presente nell’oggetto ricevuto.

Esempio essenziale in Python

Lo script seguente esegue una query per ogni parola chiave, salva la risposta completa in un file JSON e crea un CSV da usare in un foglio di calcolo o per successive elaborazioni. È compatibile con Python 3.8+ e utilizza solo la libreria standard. Prima di eseguirlo, impostate la variabile d’ambiente con la chiave di licenza. Adattate l’elenco delle parole chiave e il numero di risultati al vostro caso d’uso.

import csv
import json
import os
import time
from datetime import datetime, timezone
from pathlib import Path
from urllib.parse import urlencode
from urllib.request import urlopen

BASE_URL = "https://tiktok.evelode.com/searchVideo"
LICENSE_KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
KEYWORDS = ["borraccia termica", "borraccia sportiva", "unboxing borraccia"]
REGION = "US"
COUNT = 20


def request_search(keyword):
    params = {
        "license_key": LICENSE_KEY,
        "keyword": keyword,
        "count": COUNT,
        "region": REGION,
        "sort_by": "relevance",
        "date_posted": "this-month",
    }
    url = BASE_URL + "?" + urlencode(params)
    with urlopen(url, timeout=60) as response:
        return json.loads(response.read().decode("utf-8"))


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

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

    for item in tiktok.get("aweme_list") or []:
        if isinstance(item, dict):
            rows.append(item)

    for item in tiktok.get("search_item_list") or []:
        video = item.get("aweme_info") if isinstance(item, dict) else None
        if isinstance(video, dict):
            rows.append(video)

    return rows, tiktok


Path("raw").mkdir(exist_ok=True)
seen = set()
records = []

for keyword in KEYWORDS:
    payload = request_search(keyword)
    collected_at = datetime.now(timezone.utc).isoformat()
    safe_name = keyword.replace(" ", "_")
    raw_path = Path("raw") / (safe_name + ".json")
    raw_path.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")

    videos, tiktok = extract_videos(payload)
    for video in videos:
        video_id = video.get("aweme_id")
        if not video_id:
            continue
        dedupe_key = (keyword, video_id)
        if dedupe_key in seen:
            continue
        seen.add(dedupe_key)

        stats = video.get("statistics") or {}
        author = video.get("author") or {}
        records.append({
            "collected_at": collected_at,
            "keyword": keyword,
            "video_id": video_id,
            "url": video.get("share_url"),
            "created_at_epoch": video.get("create_time"),
            "description": video.get("desc"),
            "author": author.get("nickname"),
            "username": author.get("unique_id"),
            "views": stats.get("play_count"),
            "likes": stats.get("digg_count"),
            "comments": stats.get("comment_count"),
            "shares": stats.get("share_count"),
            "saves": stats.get("collect_count"),
            "cursor": tiktok.get("cursor"),
        })

    time.sleep(1)

fieldnames = [
    "collected_at", "keyword", "video_id", "url", "created_at_epoch",
    "description", "author", "username", "views", "likes", "comments",
    "shares", "saves", "cursor",
]
with open("tiktok_creatives.csv", "w", newline="", encoding="utf-8") as output:
    writer = csv.DictWriter(output, fieldnames=fieldnames)
    writer.writeheader()
    writer.writerows(records)

print("Saved", len(records), "video rows to tiktok_creatives.csv")

Lo script associa la parola chiave al video: è importante se lo stesso contenuto viene individuato da più query. In questo esempio, la deduplicazione avviene all’interno di ciascuna parola chiave, quindi lo stesso ID può comparire su righe distinte per query diverse. Per ottenere una tabella unica senza duplicati, sostituite la chiave (keyword, video_id) con video_id e accumulate le parole chiave in un elenco o in una tabella di associazione separata.

Il codice esegue intenzionalmente una sola query per parola e non scorre automaticamente le pagine. Se servono altre pagine, la documentazione definisce cursor come il valore per scorrere i risultati, restituito dalla risposta precedente. Va passato come valore opaco, senza calcolarlo autonomamente. Verificate lo schema di paginazione su una risposta di prova per il vostro flusso di lavoro e fermatevi quando non ci sono più risultati o un cursore successivo.

Come ottenere una tabella confrontabile

Il CSV può essere aperto in un foglio di calcolo, caricato in un database o usato in Python per calcolare aggregati. Per il primo report, raggruppate le righe per data di raccolta, parola chiave e formato del video. È preferibile assegnare il formato dopo aver esaminato la descrizione e il video stesso, per esempio «dimostrazione», «unboxing», «recensione» o «confronto». Per un piccolo campione, la classificazione può essere manuale; in alternativa, si può chiedere a un modello di proporre un’etichetta preliminare, da far poi verificare a una persona.

Se automatizzate la classificazione dei testi, passate al modello solo i campi necessari, come la descrizione e l’ID, e chiedetegli di restituire un’etichetta tra quelle approvate in anticipo. Conservate la descrizione originale separatamente dal risultato della classificazione. In questo modo l’analista potrà verificare un’etichetta dubbia e ricalcolare il report dopo aver modificato la tassonomia, senza inviare una nuova richiesta all’API.

Per le metriche comparative, utilizzate valori raccolti nello stesso momento. Per esempio, il rapporto tra Mi piace e visualizzazioni si calcola come likes / views, se entrambi i campi sono disponibili e le visualizzazioni sono maggiori di zero. Analogamente, si può calcolare la quota di commenti o condivisioni. Questi rapporti descrivono i contatori pubblici correnti del singolo video; non misurano la copertura di un pubblico specifico, il completamento della visualizzazione o le conversioni. Per prendere decisioni aziendali, confrontateli con le vostre campagne e usateli come riferimento per scegliere idee, non come promessa dei risultati ottenibili replicando il formato di altri.

La mediana è spesso più utile della media se il campione include alcuni video con numeri molto elevati. Confrontate la mediana delle visualizzazioni e delle reazioni tra gruppi solo adottando regole di raccolta identiche: stesso insieme di query, stessa area geografica, stesso filtro temporale e orari di rilevazione ravvicinati. Annotate i parametri di ogni esecuzione insieme alla data. Se cambiano i criteri di ricerca o il campione, le differenze tra due report potrebbero dipendere anche dal metodo.

Nuove esecuzioni e monitoraggio dei cambiamenti

Per trasformare un’analisi occasionale in monitoraggio, eseguite lo script secondo una pianificazione, per esempio ogni giorno o una volta alla settimana, e aggiungete a ogni record la data di raccolta. Per ciascun video, memorizzate coppie «orario dell’istantanea — valore del contatore». In questo modo potrete osservare come cambiano le metriche pubbliche tra una rilevazione e l’altra, mantenendo separato ogni punto di misurazione. Non sovrascrivete i vecchi contatori con i valori correnti: altrimenti la loro evoluzione andrà persa.

In produzione, trasferite il JSON grezzo dalla cartella locale a uno storage di oggetti o a un altro sistema di archiviazione e inserite le righe normalizzate in un database con una chiave univoca, per esempio la combinazione di ID del video e orario di raccolta. Aggiungete un log degli errori che non contenga la chiave segreta, un numero massimo di tentativi e una notifica in caso di richiesta non riuscita. Se l’errore è temporaneo, la richiesta può essere ripetuta dopo un’attesa; se è un errore strutturale, è meglio conservare la risposta e segnalare l’esecuzione per la verifica, così che il problema non produca silenziosamente un report vuoto.

Non usate cursor come identificatore permanente della ricerca: è un marcatore per continuare a scorrere i risultati. Conservatelo insieme ai parametri della relativa query, utilizzatelo solo per proseguire quella ricerca e non mescolate pagine appartenenti a parole chiave diverse. Registrate inoltre il numero effettivo di risultati elaborati: il valore richiesto con count indica la dimensione desiderata della risposta, ma non garantisce di includere tutte le pubblicazioni pertinenti.

Come ampliare il flusso di lavoro

Se il campione ottenuto dalle query è troppo rumoroso, potete monitorare separatamente profili pubblici specifici o hashtag. La documentazione include gli endpoint /getUserFeed e /getHashtagFeed, con parametri di query e paginazione. Si tratta di campioni diversi, con regole di continuazione specifiche: per il feed di un profilo si usa max_cursor, mentre per un hashtag si usa cursor. Integrateli come fonti separate e salvate il tipo di fonte e i parametri, in modo da non mescolare i risultati delle query per parola chiave con le pubblicazioni di un profilo o di un hashtag.

Per un team senza infrastruttura propria, il CSV può essere trasferito in Google Sheets tramite API: la documentazione di Google Sheets API descrive la lettura e la scrittura dei valori delle celle. Create fogli separati per le esecuzioni grezze, i video normalizzati e il riepilogo. Questa soluzione è utile per la classificazione collaborativa; quando lo storico diventa difficile da gestire in un foglio di calcolo, trasferite le righe in un database SQL mantenendo gli stessi campi e la provenienza dei dati.

Per un agente AI, un ruolo sensato consiste nel preparare un breve riepilogo dei record già raccolti e normalizzati: raggruppare le descrizioni, proporre formati e mettere in evidenza valori insoliti. Non è opportuno chiedere all’agente di formulare affermazioni sull’intera piattaforma a partire da un campione limitato. Fornite il periodo, l’elenco delle query e il numero di righe; chiedetegli di citare gli ID dei video e di lasciare vuoti i campi incerti o mancanti. L’analista dovrà poi verificare gli esempi usando i link salvati.

Risultato finale

Una volta configurato, il team avrà un registro riproducibile dei video individuati, con ID, link, descrizioni, autori, orari di pubblicazione e contatori pubblici disponibili. La risposta grezza archiviata consente di verificare le trasformazioni, mentre il CSV permette di ordinare rapidamente i video, filtrare per parola chiave e confrontare le istantanee per data. Da questi dati si può ricavare un riepilogo settimanale: quali formati ricorrono, quali pubblicazioni meritano di essere esaminate e quali ipotesi creative vale la pena testare con i propri contenuti.

Il risultato pratico non è una classifica universale dei concorrenti, ma un campione rigoroso con una provenienza chiara. La sua qualità dipende dalle query, dai filtri e dal periodo di osservazione scelti. Conservate quindi i parametri di raccolta, verificate manualmente singoli video e distinguete le metriche disponibili dalla loro interpretazione. Questo processo aiuta a sostituire i link salvati alla rinfusa con dati confrontabili e a discutere i contenuti creativi sulla base di esempi concreti.

Potete verificare l’endpoint di ricerca e i relativi parametri nella documentazione ufficiale di jsonscraper; la descrizione del servizio e l’accesso sono disponibili nella pagina di TikTok Scraper API. Iniziate con alcune frasi di ricerca, salvate una risposta di prova e controllatene la struttura prima di programmare le esecuzioni.