Come trovare video TikTok con domande sul tuo prodotto e creare un report

Se i clienti parlano del tuo prodotto su TikTok, una ricerca per nome del marchio può fornire al team materiale utile per compilare un elenco di domande ricorrenti. Il risultato pratico è un CSV con la descrizione del video, l’autore, il link e i conteggi delle interazioni disponibili. Il file può essere condiviso con il team di assistenza o usato come input per una classificazione per argomento.

Prendiamo come esempio la domanda «come si usa la macchina da caffè Acme». Lo script qui sotto invia una richiesta alla ricerca di TikTok, estrae con attenzione i video da due varianti documentate della struttura di risposta e salva i risultati trovati. Il team controlla poi manualmente le descrizioni, raggruppa le formulazioni simili e le trasforma in temi per le FAQ o in suggerimenti per la scheda prodotto.

Perché conviene trasformare la ricerca in una tabella

La consultazione manuale dei risultati di ricerca rende difficile ripetere il controllo: bisogna ritrovare i risultati e spesso gli appunti restano nel browser o nelle conversazioni. Una tabella salvata offre un unico elenco di lavoro: ogni voce include l’identificativo del video, il link, la descrizione, l’autore e le metriche disponibili. È possibile integrare una nuova esecuzione in una pianificazione e usare l’archivio JSON per capire che cosa ha restituito l’API in una determinata esecuzione.

È importante tenere presente un limite del metodo: la ricerca restituisce i risultati trovati per la query, non un catalogo completo garantito di tutte le menzioni. La tabella è quindi utile per individuare esempi e osservare le domande ricorrenti; le conclusioni sulla frequenza andrebbero corroborate con esecuzioni ripetute e una verifica manuale.

Che cosa restituisce la ricerca

Nella documentazione di TikTok Scraper API, l’endpoint /searchVideo richiede il parametro obbligatorio keyword. Tra i parametri supportati sono elencati anche count, cursor, date_posted, sort_by e region. Per questo caso d’uso bastano la query e il numero di risultati.

La risposta contiene uno stato esterno e l’oggetto tiktok. Nello schema verificato, i video possono trovarsi in aweme_list oppure negli elementi di search_item_list, all’interno del campo aweme_info. Il codice gestisce entrambe le forme ed estrae solo i campi effettivamente presenti. A seconda del risultato, sono disponibili l’identificativo del video, la descrizione, il link, il nome e l’ID dell’autore, la data di pubblicazione e i conteggi di visualizzazioni, Mi piace, commenti e condivisioni.

Un raccoglitore essenziale in Python

Installa la libreria per le richieste e imposta la chiave nella variabile d’ambiente JSONSCRAPER_TIKTOK_LICENSE_KEY. Il codice è compatibile con Python 3.8+. Salva la risposta originale in JSON e le righe normalizzate in CSV. Il segreto viene passato alla richiesta, ma non mostrato sullo schermo.

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

import requests

API_KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
KEYWORD = "Acme кофемашина"

response = requests.get(
    "https://tiktok.evelode.com/searchVideo",
    params={
        "license_key": API_KEY,
        "keyword": KEYWORD,
        "count": 30,
        "region": "US",
    },
    timeout=60,
)
response.raise_for_status()
payload = response.json()

if payload.get("status") != "ok":
    raise RuntimeError("TikTok API ha restituito uno stato esterno inatteso")

tiktok = payload.get("tiktok") or {}
items = list(tiktok.get("aweme_list") or [])
for result in tiktok.get("search_item_list") or []:
    video = result.get("aweme_info")
    if video:
        items.append(video)

# Rimuove i duplicati mantenendo l’ordine della prima occorrenza.
unique = {}
for item in items:
    video_id = item.get("aweme_id")
    if video_id:
        unique.setdefault(video_id, item)

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

columns = [
    "video_id", "description", "share_url", "author", "author_id",
    "created_at", "views", "likes", "comments", "collected_at"
]
with open("data/videos.csv", "w", newline="", encoding="utf-8") as file:
    writer = csv.DictWriter(file, fieldnames=columns)
    writer.writeheader()
    for item in unique.values():
        author = item.get("author") or {}
        stats = item.get("statistics") or {}
        created = item.get("create_time")
        writer.writerow({
            "video_id": item.get("aweme_id"),
            "description": item.get("desc"),
            "share_url": item.get("share_url"),
            "author": author.get("nickname"),
            "author_id": author.get("uid"),
            "created_at": created,
            "views": stats.get("play_count"),
            "likes": stats.get("digg_count"),
            "comments": stats.get("comment_count"),
            "collected_at": stamp,
        })

print(f"Righe salvate: {len(unique)}")

Puoi installare la dipendenza con il comando python -m pip install requests. Se un campo manca da una voce specifica, il codice lascia vuota la cella corrispondente. Questo è importante per le metriche: un valore vuoto indica che il campo non è stato restituito e non viene sostituito con zero.

Come trasformare il CSV in un elenco utile di domande

Il primo passaggio è filtrare il contenuto delle descrizioni. Si possono cercare parole come «come», «perché», «non funziona», il nome del modello e i nomi caratteristici dei componenti. Il filtro crea una coda da sottoporre a revisione editoriale, ma da solo non determina l’intento dell’autore: una menzione del marchio potrebbe essere una recensione, una battuta o una domanda sulla compatibilità.

Per raggruppare i temi, passa al classificatore solo i campi testuali necessari: la descrizione e, se è pertinente al compito, un identificativo della voce anonimizzato. Chiedi di restituire categorie predefinite, per esempio «primo avvio», «pulizia», «compatibilità», «malfunzionamento» e «acquisto». Conserva la descrizione originale accanto alla categoria, così che un membro del team possa verificare l’assegnazione e correggere eventuali errori.

Un report operativo può includere il tema, il numero di esempi trovati, link a qualche video rappresentativo e una colonna separata «verificato da una persona». Il numero di esempi nel set raccolto descrive i risultati di quella query e del periodo di raccolta; non equivale alla percentuale di tutti i clienti che riscontrano un problema.

Paginazione ed esecuzioni ricorrenti

Se serve una pagina successiva di risultati, la documentazione indica cursor come parametro di scorrimento: passa al nuovo request il valore del cursore restituito dalla risposta precedente. Trattalo come un token opaco e interrompi la ricerca quando la risposta non contiene altri risultati o l’API segnala che non ci sono altre pagine. Per un progetto pilota limitato, è ragionevole iniziare con una sola richiesta, controllare i risultati e aggiungere la paginazione solo in seguito.

Per raccogliere i dati con regolarità, esegui lo script secondo una pianificazione tramite l’utilità di pianificazione del sistema operativo o la CI. Salva un JSON originale separato per ogni esecuzione e aggiungi alla tabella l’ora della raccolta. Quando accumuli uno storico, deduplica le voci in base all’ID del video, ma conserva separatamente le acquisizioni ripetute se devi monitorare l’evoluzione dei conteggi. Il confronto delle metriche è significativo solo se sono disponibili più acquisizioni della stessa voce.

Conserva la chiave in un gestore di segreti della CI o in una variabile d’ambiente, limita l’accesso all’archivio e definisci un periodo di conservazione interno. Prima di trasferire i dati a un sistema di classificazione, verifica quali campi siano davvero necessari. In questo modo si riduce la duplicazione non necessaria dei dati degli utenti e si semplifica il controllo degli accessi.

Quale risultato ottiene il team

Al termine dell’esecuzione avrai un archivio della risposta originale e un CSV con i video trovati e i campi disponibili. Il team di assistenza potrà verificare i link e raccogliere le domande ricorrenti; il marketing potrà osservare le formulazioni usate dal pubblico per descrivere il problema; l’analista potrà ripetere la raccolta e confrontare le osservazioni in date diverse.

Per iniziare, formula una query mirata con il nome del prodotto e un problema specifico, controlla manualmente 20–30 voci trovate e perfeziona il vocabolario delle categorie. Poi puoi aggiungere alcune query tematiche, una pianificazione e l’esportazione in un foglio di calcolo o in un database. Le funzionalità dell’endpoint e i relativi parametri sono descritti nella descrizione di TikTok Scraper API; verifica la query scelta prima di avviare un monitoraggio più ampio.