TikTok: trasforma i risultati di ricerca in un elenco settimanale di temi per l’assistenza

Al team di assistenza serve un elenco di video TikTok pubblici in cui le persone discutono di una funzione poco chiara o fanno domande sul prodotto. La ricerca manuale è difficile da ripetere in modo coerente e le risposte dell’API di ricerca possono contenere i video in punti diversi del JSON. Di seguito trovi uno script Python essenziale che cerca risultati per parole chiave, unisce entrambe le strutture, rimuove i duplicati in base all’ID e salva i video trovati in un CSV.

Quale risultato produce lo script

Otterrai una tabella con l’ID del video, il link, la descrizione, l’ora di pubblicazione, l’autore e i contatori delle interazioni disponibili. Il team di assistenza o marketing potrà indicare manualmente quali temi richiedono una risposta, un aggiornamento delle istruzioni o una verifica nel CRM interno. La tabella rispecchia i risultati restituiti dall’API per le query specificate: considerala un campione di lavoro da esaminare, non un catalogo esaustivo di tutte le discussioni.

Lo script si occupa della raccolta e dell’ordinamento iniziale. Non determina automaticamente se una descrizione sia una domanda, un reclamo o uno scherzo: è preferibile aggiungere l’etichetta dopo una verifica manuale oppure con un classificatore separato, registrando il testo originale e il motivo della decisione.

Cosa richiedere e com’è strutturata la risposta

Per cercare video, jsonscraper documenta la route GET /searchVideo sull’host https://tiktok.evelode.com. Il parametro obbligatorio è keyword; si possono passare anche count, regione, ordinamento, periodo di pubblicazione e cursore per la pagina successiva. Per esempio, puoi ripetere la ricerca usando diverse frasi definite in anticipo: il nome di una funzione, una formulazione comune di errore e una breve domanda sulla configurazione. I parametri e i valori ammessi sono elencati nella guida di TikTok API.

La ricerca presenta una particolarità importante per il parser: l’array aweme_list può essere vuoto, mentre gli oggetti trovati si trovano in search_item_list, ciascuno con aweme_info. Per questo il gestore verifica entrambe le forme. Un esempio di risposta e i campi osservati durante la verifica del 25 ottobre 2026 sono riportati nella specifica primaria di jsonscraper; i campi delle statistiche potrebbero non essere presenti, quindi il codice non inserisce valori inventati.

Prepara la chiave e l’elenco delle query

Salva la chiave nella variabile d’ambiente JSONSCRAPER_TIKTOK_LICENSE_KEY, non nel file sorgente. Nella shell di Linux o macOS puoi farlo così:

export JSONSCRAPER_TIKTOK_LICENSE_KEY="la_tua_chiave"

Installa la libreria per le richieste e crea il file queries.txt con un’espressione di ricerca per riga, per esempio nome prodotto configurazione e nome funzione non funziona. Scegli le formulazioni in base alla lingua del pubblico e tienile in un elenco separato, così le esportazioni settimanali potranno confrontare sempre le stesse query.

python -m pip install requests

Raccogli e normalizza i video trovati

L’esempio è compatibile con Python 3.8+. Esegue una richiesta per ogni frase con un limite di risultati, verifica gli errori HTTP e lo stato restituito dall’API, quindi salva soltanto i campi effettivamente presenti. I risultati duplicati vengono unificati tramite aweme_id e tutte le query che hanno restituito un video vengono registrate nel campo keywords. Il campo separato collected_at_utc registra l’ora di acquisizione dei dati per confrontare le esecuzioni successive.

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

import requests

BASE_URL = "https://tiktok.evelode.com/searchVideo"
API_KEY = os.environ.get("JSONSCRAPER_TIKTOK_LICENSE_KEY")

if not API_KEY:
    raise SystemExit("Imposta JSONSCRAPER_TIKTOK_LICENSE_KEY")


def get_items(tiktok):
    """Estrae i video da entrambe le forme documentate della risposta di ricerca."""
    items = list(tiktok.get("aweme_list") or [])
    for entry in tiktok.get("search_item_list") or []:
        info = entry.get("aweme_info") if isinstance(entry, dict) else None
        if info:
            items.append(info)
    return items


with open("queries.txt", encoding="utf-8") as query_file:
    queries = [line.strip() for line in query_file if line.strip()]

collected_at = datetime.now(timezone.utc).isoformat()
videos = {}

for keyword in queries:
    response = requests.get(
        BASE_URL,
        params={
            "license_key": API_KEY,
            "keyword": keyword,
            "count": 30,
            "region": "US",
            "sort_by": "relevance",
        },
        timeout=30,
    )
    response.raise_for_status()
    payload = response.json()

    if payload.get("status") != "ok":
        print("Stato API non riuscito per la query:", keyword, file=sys.stderr)
        continue

    tiktok = payload.get("tiktok") or {}
    for item in get_items(tiktok):
        video_id = item.get("aweme_id")
        if not video_id:
            continue

        if video_id not in videos:
            author = item.get("author") or {}
            stats = item.get("statistics") or {}
            videos[video_id] = {
                "aweme_id": video_id,
                "keywords": [keyword],
                "description": item.get("desc"),
                "share_url": item.get("share_url"),
                "create_time": item.get("create_time"),
                "author": 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"),
                "collected_at_utc": collected_at,
            }
        elif keyword not in videos[video_id]["keywords"]:
            videos[video_id]["keywords"].append(keyword)

columns = [
    "aweme_id", "keywords", "description", "share_url", "create_time",
    "author", "play_count", "digg_count", "comment_count", "share_count",
    "collected_at_utc",
]
with open("tiktok_support_review.csv", "w", newline="", encoding="utf-8-sig") as output:
    writer = csv.DictWriter(output, fieldnames=columns)
    writer.writeheader()
    for video in videos.values():
        row = dict(video)
        row["keywords"] = " | ".join(row["keywords"])
        writer.writerow(row)

print("Numero di video unici trovati e salvati:", len(videos))

La richiesta viene inviata tramite il parametro params, così la libreria codifica correttamente le frasi di ricerca nell’URL. La chiave si trova nel parametro della query, come indicato nella documentazione; non stampare l’URL completo della richiesta nei log dell’applicazione. Per la diagnostica registra il codice della risposta HTTP, la frase cercata e l’ora di esecuzione, escludendo segreti e dati personali non necessari.

Come leggere il CSV senza trarre conclusioni errate

La colonna keywords contiene tutte le frasi che hanno restituito un video; collected_at_utc permette di distinguere l’ora di pubblicazione da quella di raccolta. L’ID è utile per la deduplicazione e il link per la verifica umana. Un contatore vuoto significa che il campo era assente nella risposta specifica, non che il suo valore fosse zero.

Per una prima classificazione, aggiungi alla copia di lavoro del CSV le colonne tema, tipo di segnale, richiede risposta e link al materiale interno. I temi dovrebbero corrispondere al tuo prodotto: per esempio, installazione, pagamenti, compatibilità o risoluzione dei problemi. Questo schema trasforma l’esportazione in una coda di revisione e consente di verificare la decisione rispetto al video originale.

Pianifica la raccolta

Per prima cosa esegui lo script manualmente e controlla alcune righe e i relativi link. Poi aggiungilo a cron, a un’attività CI o a uno scenario di automazione in grado di eseguire un processo Python. Per i rapporti periodici, conserva ogni esportazione oppure aggiungi le righe a un archivio con una chiave univoca per video e la data dello snapshot. In questo modo il team potrà distinguere le nuove pubblicazioni trovate dalle osservazioni ripetute e seguire le variazioni dei contatori disponibili tra un’esecuzione e l’altra.

Il parametro cursor è previsto per scorrere i risultati e va passato dalla risposta della chiamata precedente. La paginazione è intenzionalmente esclusa da questo esempio essenziale: è più semplice verificare e riprodurre un insieme limitato di query. Se aggiungi pagine, conserva il cursore senza interpretarlo, interrompi la raccolta in base al flag che indica la presenza di altre pagine e imposta un limite massimo di chiamate per esecuzione. La richiesta API restituisce un campione: non interpretare il numero di righe come una copertura completa di TikTok.

Limiti pratici di utilizzo

I risultati di ricerca sono adatti a trovare video tramite formulazioni già note al team. Aiutano a raccogliere materiale da classificare, ma non sostituiscono le richieste ricevute, le analisi del proprio sito o la verifica del contesto del video. La descrizione potrebbe non cogliere il contenuto effettivo del video e le metriche disponibili riflettono lo stato dei dati al momento dell’acquisizione. Registra temi e conclusioni separatamente dai campi originali, così i dipendenti potranno riesaminare la classificazione.

Prima di avviare il monitoraggio periodico, stabilisci chi può accedere all’esportazione, per quanto tempo conservare i dati e per quale scopo utilizzare le informazioni pubbliche. Conserva solo i campi necessari per esaminare il prodotto e prediligi i link alle pubblicazioni originali invece di copiare i file multimediali. Per inviare richieste e verificare le opzioni d’integrazione disponibili, consulta la pagina TikTok Scraper API e la documentazione della route di ricerca.