Come rilevare i video TikTok con coinvolgimento in crescita senza confrontare le visualizzazioni totali

Per capire se un determinato video TikTok sta suscitando reazioni, confronta le sue metriche pubbliche con la rilevazione precedente. Una singola ricerca mostra le visualizzazioni e le reazioni accumulate fino a quel momento; raccogliere di nuovo gli stessi video individuati consente di osservare le variazioni tra due esecuzioni. Di seguito trovi una pipeline Python essenziale e funzionante: invia una ricerca, salva le metriche in CSV e calcola le differenze.

Che cosa misura questo monitoraggio?

Lo script è adatto a chi si occupa di marketing, analisi o sviluppo e ha bisogno di un elenco di video individuati su un argomento e di uno storico verificabile delle osservazioni. Per esempio, un team può monitorare regolarmente i video sul lancio di un prodotto o su una specifica ricerca del pubblico e vuole vedere quali hanno ottenuto più visualizzazioni, Mi piace, commenti o condivisioni rispetto al controllo precedente.

L’unità di confronto chiave è il video, identificato da aweme_id. Per ogni record vengono salvati l’orario di raccolta, l’identificativo, la descrizione, l’URL, il nome dell’autore e i contatori disponibili. In seguito, le due rilevazioni vengono abbinate tramite l’identificativo. In questo modo, la crescita delle visualizzazioni di un video non viene confusa con quelle accumulate da un altro.

Il risultato descrive solo i video restituiti da una determinata ricerca in una determinata esecuzione. I risultati della ricerca possono variare e alcuni campi statistici potrebbero mancare. È quindi utile conservare le rilevazioni e l’orario di raccolta e considerare il report come un’osservazione dei video già individuati, non come un catalogo completo delle pubblicazioni sull’argomento.

Come funziona la raccolta tramite API?

La documentazione di TikTok Scraper API descrive l’endpoint GET /searchVideo. Per la ricerca è obbligatoria la stringa keyword; tra i parametri facoltativi figurano count, region, sort_by e date_posted. La chiave API viene passata come license_key. La documentazione indica come endpoint di base https://tiktok.evelode.com.

La risposta contiene uno stato esterno e un oggetto tiktok. Nei risultati di ricerca, i video possono trovarsi in tiktok.aweme_list oppure all’interno di tiktok.search_item_list[].aweme_info. Il gestore qui sotto supporta entrambe le strutture. Le metriche vengono estratte da statistics, compresi play_count, digg_count, comment_count e share_count; se un valore manca, il campo resta vuoto anziché essere impostato a zero.

La documentazione degli endpoint elenca cursor per scorrere i risultati della ricerca e specifica i valori ammessi per date_posted e sort_by. Per un monitoraggio semplice e ripetibile, basta iniziare recuperando una pagina di risultati e registrando la risposta; aggiungi la paginazione solo se necessario. Se ti serve, passa il cursore ricevuto senza modificarlo.

Esempio funzionante in Python

Installa la libreria per le richieste con il comando python -m pip install requests e imposta la chiave nella variabile d’ambiente JSONSCRAPER_TIKTOK_LICENSE_KEY. Lo script accetta una frase di ricerca come argomento e aggiunge le rilevazioni dei video trovati a un unico file CSV. Il codice è compatibile con Python 3.8 e versioni successive.

import csv
import os
import sys
from datetime import datetime, timezone
from pathlib import Path

import requests

BASE_URL = "https://tiktok.evelode.com/searchVideo"
CSV_PATH = Path("tiktok_video_snapshots.csv")
FIELDS = [
    "collected_at", "aweme_id", "author", "description", "share_url",
    "play_count", "digg_count", "comment_count", "share_count",
]


def extract_items(payload):
    """Support observed search response layouts."""
    data = payload.get("tiktok") or {}
    items = data.get("aweme_list") or []
    if items:
        return items

    found = []
    for result in data.get("search_item_list") or []:
        info = result.get("aweme_info")
        if info:
            found.append(info)
    return found


def main():
    key = os.environ.get("JSONSCRAPER_TIKTOK_LICENSE_KEY")
    if not key:
        raise SystemExit("Set JSONSCRAPER_TIKTOK_LICENSE_KEY first")
    if len(sys.argv) < 2:
        raise SystemExit('Usage: python collect.py "search phrase"')

    params = {
        "license_key": key,
        "keyword": sys.argv[1],
        "count": 20,
        "region": "US",
        "sort_by": "relevance",
        "date_posted": "this-week",
    }
    response = requests.get(BASE_URL, params=params, timeout=30)
    response.raise_for_status()
    payload = response.json()

    if payload.get("status") != "ok":
        raise RuntimeError("API returned a non-ok outer status")
    data = payload.get("tiktok") or {}
    items = extract_items(payload)
    collected_at = datetime.now(timezone.utc).isoformat()

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

    write_header = not CSV_PATH.exists()
    with CSV_PATH.open("a", newline="", encoding="utf-8") as file:
        writer = csv.DictWriter(file, fieldnames=FIELDS)
        if write_header:
            writer.writeheader()
        writer.writerows(rows)

    print("Saved", len(rows), "returned videos")
    print("has_more:", data.get("has_more"), "cursor:", data.get("cursor"))


if __name__ == "__main__":
    main()

Per esempio, esegui python collect.py "ricerca su un prodotto". La libreria inserisce la chiave nei parametri dell’URL; lo script non la stampa nel terminale. Non salvare l’URL completo della richiesta nei log pubblici, perché contiene la chiave. Per un sistema in produzione, usa un archivio di segreti e limita l’accesso al file delle rilevazioni.

Come calcolare la crescita tra un’esecuzione e l’altra?

Lo script salva intenzionalmente tutte le osservazioni invece di sovrascrivere i valori precedenti. Il piccolo analizzatore qui sotto abbina le due rilevazioni più recenti di ciascun video e mostra la differenza tra i contatori. Se una metrica non è disponibile in uno dei due record, il risultato viene indicato come non disponibile.

import csv
from collections import defaultdict
from pathlib import Path

rows_by_video = defaultdict(list)
with Path("tiktok_video_snapshots.csv").open(encoding="utf-8", newline="") as file:
    for row in csv.DictReader(file):
        if row["aweme_id"]:
            rows_by_video[row["aweme_id"]].append(row)

metrics = ("play_count", "digg_count", "comment_count", "share_count")
for video_id, snapshots in rows_by_video.items():
    snapshots.sort(key=lambda row: row["collected_at"])
    if len(snapshots) < 2:
        continue
    previous, latest = snapshots[-2], snapshots[-1]
    changes = {}
    for metric in metrics:
        old, new = previous[metric], latest[metric]
        changes[metric] = int(new) - int(old) if old and new else None
    print(video_id, changes, latest["share_url"])

La differenza è la sottrazione tra due valori salvati, non un tasso di crescita con periodicità garantita. Se le esecuzioni avvengono a intervalli diversi, aggiungi il calcolo del tempo trascorso tra i campi collected_at e confronta la crescita sull’intervallo effettivo. I contatori possono variare tra un’osservazione e l’altra; le date e gli orari salvati indicano quando sono stati acquisiti i valori utilizzati.

Come automatizzare e interpretare il report?

Per un report giornaliero, inserisci la raccolta in un pianificatore di attività sul server o nella CI, definisci un elenco fisso di frasi di ricerca e salva i CSV oppure carica le righe in un database. Se i risultati si ripetono, elimina i duplicati all’interno della stessa rilevazione usando aweme_id. Per conservare lo storico, salva il JSON originale insieme alle colonne normalizzate: sarà più semplice rielaborarlo se cambia lo schema del report.

Nella tabella è utile mostrare l’ID e l’URL del video, l’autore, la descrizione, l’orario di raccolta e le differenze per ciascuna metrica. Ordinare per crescita delle visualizzazioni risponde alla domanda sulla diffusione; l’aumento dei commenti o delle condivisioni aiuta invece a individuare altri tipi di reazione. Non combinare questi indicatori in un’unica classifica senza definire una regola esplicita: ogni contatore ha un significato diverso.

Il pianificatore può inviare il report via e-mail, a un foglio di calcolo o a un canale interno, ma questo passaggio dipende dalla tua infrastruttura: l’esempio sopra si limita a raccogliere e analizzare i dati. Per una raccolta più completa, puoi scorrere le pagine dei risultati, salvando il cursore e terminando il ciclo quando l’API segnala che non ci sono altre pagine. Il cursore di ricerca è un valore opaco restituito dalla risposta: non calcolarlo autonomamente. Anche scorrendo tutte le pagine, si descrivono i risultati restituiti, senza garantire un elenco completo di tutte le pubblicazioni pertinenti.

Il risultato pratico atteso è un registro riproducibile delle osservazioni e una tabella delle variazioni per i video individuati. Ti aiuta a notare quali pubblicazioni hanno modificato i propri contatori pubblici tra un controllo e l’altro e a fornire link specifici a chi può svolgere un’analisi approfondita. I dettagli del prodotto e l’accesso all’API sono disponibili nella pagina TikTok Scraper API.

Che cosa controllare prima di programmare l’esecuzione?

• Verifica che lo stato esterno della risposta sia ok prima di elaborare tiktok.
• Controlla entrambe le strutture possibili degli elementi di ricerca; se manca l’elenco, la raccolta deve risultare vuota, senza generare un errore.
• Conserva i valori originali e le marche temporali. Una metrica vuota deve rimanere vuota.
• Usa le stesse ricerche e gli stessi parametri per rendere più chiaro il confronto tra le rilevazioni; registra accanto al report eventuali modifiche a queste impostazioni.
• Monitora la frequenza delle esecuzioni, gli errori HTTP e le dimensioni dello storico; rispetta inoltre le regole applicabili della piattaforma e i requisiti per il trattamento dei dati.

In sintesi, per ottenere un risultato osservabile basta ripetere la stessa ricerca, identificare i video tramite aweme_id e confrontare nel tempo le metriche salvate. Questo approccio risponde a una domanda pratica circoscritta: quali video già individuati hanno modificato i propri contatori pubblici tra due controlli? Inoltre, mantiene i dati originali disponibili per verifiche e ulteriori elaborazioni.