Come individuare le domande ricorrenti su un prodotto su TikTok

Se gli acquirenti pongono la stessa domanda in diversi video su TikTok, è utile che il team di assistenza disponga di un elenco dei video originali e delle formulazioni da verificare. Si può iniziare raccogliendo i risultati di ricerca per più query, unendoli in base all’ID del video e sottoponendo il campione a etichettatura manuale.

Di seguito è riportato uno script Python che raccoglie i risultati restituiti e crea un CSV con i link, le descrizioni dei video e le frasi di ricerca con cui è stato trovato ciascun video. Aiuta a individuare le sovrapposizioni tra le ricerche; da solo, però, non rileva domande semanticamente simili. Questa valutazione spetta a uno specialista o a un classificatore separato, con una successiva verifica.

Quale domanda deve risolvere la raccolta

Supponiamo che il team venda una tazza termica e voglia capire di cosa si parla nei video pubblici. La query «la tazza termica perde» può restituire video con reclami, recensioni e istruzioni. «Come lavare una tazza termica» produrrà un campione diverso. Più espressioni formano un insieme di esempi utile per esaminare le richieste all’assistenza e pianificare i contenuti.

Il risultato dello script è una tabella con l’ID della pubblicazione, la descrizione, il link e l’elenco delle frasi di ricerca con cui è stata trovata. La presenza dello stesso video in più risultati indica una sovrapposizione tra le ricerche, ma non dimostra ancora che nel video sia stata posta una domanda ricorrente. Per creare una coda di domande, aprite i link, verificate il contesto e assegnate un tema alle formulazioni confermate.

Questo processo è utile sia a chi sviluppa l’automazione della raccolta sia agli analisti che necessitano di un insieme riproducibile da esaminare. Il collegamento al video originale consente di verificare i risultati prima di modificare le istruzioni o preparare nuovi contenuti.

Quali dati restituisce la ricerca

Il percorso /searchVideo e i relativi parametri sono elencati nella documentazione di TikTok API. keyword è obbligatorio; tra i parametri facoltativi sono indicati count, cursor, region, date_posted, sort_by e cache_timeout. L’autenticazione della richiesta avviene tramite il parametro license_key. L’esempio seguente usa una frase e la dimensione della pagina.

La struttura della risposta verificata comprende un status di primo livello e un oggetto tiktok. Gli elementi possono contenere ID, descrizione, link, informazioni sull’autore e statistiche, tra cui visualizzazioni e commenti. Alcuni campi potrebbero mancare: nel CSV questi valori restano vuoti, invece di essere trasformati in zero.

La risposta di ricerca supporta due strutture: gli elementi possono trovarsi in aweme_list oppure in search_item_list[].aweme_info. Il normalizzatore gestisce entrambe. Il codice verifica anche la presenza dell’oggetto tiktok, così da non interpretare una struttura inattesa della risposta come un risultato vuoto riuscito.

Un raccoglitore pronto all’uso in Python

L’esempio è compatibile con Python 3.8+ e con la libreria requests. Esegue una richiesta per ciascuna frase, controlla la risposta HTTP e lo stato dell’API, unisce i record per ID, conserva le frasi di ricerca corrispondenti e crea un CSV. La chiave viene letta da una variabile d’ambiente e non viene stampata.

import csv
import os
import sys
import requests

BASE_URL = "https://tiktok.evelode.com/searchVideo"
KEY = os.environ.get("JSONSCRAPER_TIKTOK_LICENSE_KEY")
QUERIES = [
    "термокружка протекает",
    "как мыть термокружку",
    "термокружка не держит тепло",
]

if not KEY:
    sys.exit("Задайте JSONSCRAPER_TIKTOK_LICENSE_KEY")

def extract_items(payload):
    data = payload.get("tiktok")
    if not isinstance(data, dict):
        raise RuntimeError("В ответе отсутствует объект tiktok")

    items = list(data.get("aweme_list") or [])
    for entry in data.get("search_item_list") or []:
        video = entry.get("aweme_info") if isinstance(entry, dict) else None
        if isinstance(video, dict):
            items.append(video)
    return items

rows = {}

for query in QUERIES:
    response = requests.get(
        BASE_URL,
        params={"license_key": KEY, "keyword": query, "count": 20},
        timeout=30,
    )
    response.raise_for_status()
    payload = response.json()
    if payload.get("status") != "ok":
        raise RuntimeError("API вернул статус, отличный от ok")

    for item in extract_items(payload):
        video_id = item.get("aweme_id")
        if not video_id:
            continue
        stats = item.get("statistics") or {}
        author = item.get("author") or {}
        row = rows.setdefault(video_id, {
            "video_id": video_id,
            "description": item.get("desc"),
            "share_url": item.get("share_url"),
            "author": author.get("nickname"),
            "play_count": stats.get("play_count"),
            "comment_count": stats.get("comment_count"),
            "matched_queries": set(),
        })
        row["matched_queries"].add(query)

fields = ["video_id", "description", "share_url", "author",
          "play_count", "comment_count", "matched_queries"]
with open("tiktok_questions.csv", "w", newline="", encoding="utf-8-sig") as file:
    writer = csv.DictWriter(file, fieldnames=fields)
    writer.writeheader()
    for row in rows.values():
        output = dict(row)
        output["matched_queries"] = " | ".join(sorted(row["matched_queries"]))
        writer.writerow(output)

Installate la dipendenza con il comando python -m pip install requests, impostate JSONSCRAPER_TIKTOK_LICENSE_KEY nell’ambiente del processo ed eseguite il file. Non inserite la chiave nel codice sorgente, nel CSV o nei log. Per pianificare l’esecuzione, avviate lo script in un ambiente protetto, dove la variabile sia accessibile al processo.

Come trasformare il CSV in una coda di domande

Dopo la raccolta, aprite i video e individuate manualmente le domande effettive; poi raggruppate le formulazioni confermate per tema, ad esempio «tenuta», «manutenzione» o «conservazione del calore». La frase di ricerca aiuta a trovare una pubblicazione, ma né la descrizione del video né la corrispondenza tra query sostituiscono la verifica del contesto.

Se utilizzate un modello linguistico, fornitegli la descrizione e chiedetegli di suggerire una breve etichetta tematica e una possibile domanda. Conservate accanto il testo originale, il link e il risultato del modello, in modo che uno specialista possa verificare su quali elementi si basa la classificazione. Non presentate la formulazione proposta dal modello come una domanda testuale se non compare nella descrizione.

Il numero di record trovati descrive soltanto i risultati restituiti per le query specificate. Non misura l’intero volume delle conversazioni o la domanda. Per i report interni, conservate la data di esecuzione, la frase originale, l’ID e la risposta grezza dell’API. In questo modo potrete confrontare le esecuzioni successive e annotare separatamente i nuovi ID.

L’esempio non include intenzionalmente la paginazione automatica. Per le pagine successive, la documentazione indica il parametro cursor: il valore va recuperato dalla risposta precedente e passato alla successiva senza modificarlo. Una pagina rappresenta solo la porzione di risultati ricevuta, non l’intero insieme.

Cosa vedrà il team

Il file tiktok_questions.csv contiene una riga per ogni ID univoco trovato con le frasi specificate. La colonna matched_queries indica con quali query è stato trovato il video. È un modo pratico per individuare le sovrapposizioni tra i risultati e selezionare esempi da verificare; la classificazione delle domande va eseguita separatamente.

Il CSV può poi essere integrato nell’automazione settimanale: un pianificatore avvia la raccolta, un archivio conserva uno snapshot e viene inviata una notifica quando compare un ID non ancora presente nel registro. Questa è una logica di orchestrazione esterna, non una funzione dell’endpoint di ricerca. Il team riceve una coda di link da analizzare, non una conclusione già pronta sulle ragioni del comportamento degli acquirenti.

I parametri dei percorsi sono disponibili nella documentazione dell’API; è possibile provare una richiesta sulla demo di TikTok API. Prima di avviare una raccolta regolare, verificate la struttura della risposta effettiva e conservate i valori necessari per passare dal riepilogo al video specifico. La descrizione del prodotto è disponibile nella pagina di TikTok Scraper API.

Il risultato utile è un insieme verificabile di video associati a specifiche espressioni di ricerca. Aiuta a selezionare i contenuti da esaminare manualmente e a conservare le fonti di ogni tema inserito nel piano editoriale.