Per studiare le conversazioni su un problema su TikTok, cerca prima i video pertinenti, quindi richiedi i commenti di ciascun video selezionato. Per un team di prodotto, il risultato può essere una raccolta di risposte JSON originali, associate alla query e al link del video. Prima di creare una coda di temi, verifica la struttura effettiva dei commenti: la documentazione conferma l’endpoint e i relativi parametri, ma non descrive i campi dei record nella risposta.
È un passaggio importante per una pipeline di analisi. I risultati della ricerca aiutano a raccogliere il contesto sul prodotto, mentre i commenti possono contenere segnalazioni di errori, domande o soluzioni alternative. Per basare la classificazione su dati reali, salva innanzitutto la risposta API senza modificarla, poi confronta i campi con lo schema effettivamente ricevuto.
Perché la ricerca dei video non basta
Il nome di un’app o di un dispositivo aiuta a trovare i video, ma la descrizione mostra soprattutto il punto di vista dell’autore. Nei commenti, gli spettatori possono discutere malfunzionamenti specifici e modalità d’uso. Raccogliere i commenti aggiunge quindi un secondo livello di dati alla selezione di ricerca, collegato al video originale.
I materiali precedenti hanno trattato il monitoraggio della ricerca su TikTok, l’estrazione di domande dalle descrizioni e l’elaborazione delle risposte di ricerca. Qui l’obiettivo è più circoscritto: raccogliere le risposte dell’endpoint dei commenti e verificarne la struttura prima di progettare una classificazione. È un approccio utile a chi sviluppa integrazioni di analisi, a chi ricerca l’esperienza utente e ai team di assistenza.
Dalla frase di ricerca a un insieme di dati verificabile
Imposta alcune query specifiche, per esempio il nome del prodotto insieme a quello di una funzione o di un modello. Salva la risposta di ricerca e gli URL dei video selezionati. Poi richiedi i commenti usando gli URL e salva ogni risposta originale separatamente. Dopo aver verificato lo schema, potrai normalizzare i campi necessari, rimuovere i duplicati e raggruppare i testi per argomento.

- Ricerca: richiedi video usando una frase chiave e verifica entrambe le strutture di risultato supportate.
- Selezione: scegli i video pertinenti e salva gli ID e gli URL.
- Raccolta dei commenti: passa gli URL all’endpoint dei commenti; per continuare la paginazione, usa il cursore restituito.
- Verifica: salva il JSON grezzo e determina i nomi effettivi dei campi dalla risposta.
- Analisi: dopo aver verificato lo schema, raggruppa i testi e sottoponi alcuni esempi a revisione umana.
Quali endpoint usare
La documentazione di TikTok Scraper API descrive GET /searchVideo, che richiede il parametro keyword. I parametri aggiuntivi includono count, cursor, date_posted, sort_by e region. Per i commenti è disponibile GET /getCommentsByUrl, che richiede video_url; tra i parametri aggiuntivi sono indicati cursor, count e region. La chiave viene passata tramite il parametro license_key.
Nella risposta di ricerca, i video possono trovarsi in tiktok.aweme_list oppure in tiktok.search_item_list[].aweme_info. L’esempio gestisce entrambe le forme, verifica lo stato esterno e salva gli oggetti trovati. Per la risposta dei commenti non presume né il nome dell’array né quello dei campi: salva e stampa il JSON ricevuto, così che sia possibile esaminarlo.
Un raccoglitore essenziale in Python
Il codice è compatibile con Python 3.8 e versioni successive. Installa requests e imposta la chiave nella variabile d’ambiente JSONSCRAPER_TIKTOK_LICENSE_KEY. Lo script scrive le risposte di ricerca e quelle dei commenti in file JSON distinti, associando ogni risposta dei commenti alla query e all’URL del video. I campi dei commenti non vengono estratti finché non è stata verificata la struttura effettiva della risposta.

import json
import os
from pathlib import Path
import requests
BASE = "https://tiktok.evelode.com"
KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
OUT = Path("tiktok_raw")
OUT.mkdir(exist_ok=True)
def get_json(path, params):
response = requests.get(
BASE + path,
params={**params, "license_key": KEY},
timeout=30,
)
response.raise_for_status()
data = response.json()
if data.get("status") != "ok":
raise RuntimeError("API returned non-ok status")
return data
def videos_from_search(data):
tiktok = data.get("tiktok") or {}
found = list(tiktok.get("aweme_list") or [])
for item in tiktok.get("search_item_list") or []:
aweme = (item or {}).get("aweme_info") or {}
if aweme:
found.append(aweme)
unique = {}
for video in found:
video_id = video.get("aweme_id")
video_url = video.get("share_url")
if video_id and video_url:
unique[video_id] = video
return list(unique.values())
for index, keyword in enumerate(("APP_NAME ошибка", "APP_NAME не работает")):
search = get_json("/searchVideo", {"keyword": keyword, "count": 10})
(OUT / f"search_{index}.json").write_text(
json.dumps(search, ensure_ascii=False, indent=2), encoding="utf-8"
)
for video in videos_from_search(search):
video_id = video["aweme_id"]
video_url = video["share_url"]
comments = get_json(
"/getCommentsByUrl",
{"video_url": video_url, "count": 30},
)
filename = f"comments_{video_id}.json"
record = {
"keyword": keyword,
"video_id": video_id,
"video_url": video_url,
"response": comments,
}
(OUT / filename).write_text(
json.dumps(record, ensure_ascii=False, indent=2), encoding="utf-8"
)
print(json.dumps(record, ensure_ascii=False, indent=2))
Lo script controlla lo stato esterno della risposta e poi scrive l’intero oggetto JSON. In questo modo è possibile esaminare le chiavi effettive, i tipi di valore e i livelli di annidamento prima di creare una tabella dei commenti. Se l’API restituisce un errore, il codice si interrompe e lo segnala invece di salvare silenziosamente un risultato non valido.
Dal JSON grezzo a una coda di temi
Dopo aver verificato una o più risposte, crea un normalizzatore basato sullo schema effettivamente rilevato. Conserva il JSON originale accanto alle righe normalizzate, così da poter verificare la trasformazione e rielaborare i dati se il codice cambia. È utile mantenere nel record il link al video, il record originale del commento, l’ora di raccolta e la versione della regola di etichettatura applicata.
Per l’etichettatura dei temi, puoi iniziare con categorie come «errore», «domanda sull’uso», «richiesta di funzionalità», «feedback» e «non pertinente al prodotto». Le regole basate su parole chiave o un classificatore possono aiutare a ordinare il campione; conserva l’etichetta assegnata separatamente dal testo originale. Prima di aprire un’attività, uno specialista dovrebbe verificare il contesto del commento e il video originale.
Per deduplicare, usa un campo identificativo solo dopo averne confermato la presenza nella risposta. Se i dati non contengono un identificatore, una chiave temporanea può combinare l’URL del video e il testo normalizzato: questo metodo raggruppa formulazioni identiche all’interno dello stesso video, ma non dimostra che i record appartengano allo stesso autore.
Automazione e provenienza dei dati
Esegui la raccolta secondo una pianificazione tramite cron, GitHub Actions o n8n. Conserva la chiave nei segreti dell’ambiente di esecuzione e non inserirla nel repository, nei file dei risultati o nei log. Mantieni le risposte JSON originali disponibili per la verifica; stabilisci tempi di conservazione e autorizzazioni in base alle esigenze del team e alle regole della piattaforma applicabili.
Per monitorare il funzionamento della pipeline, registra il numero di ricerche completate con successo, di video unici trovati, di risposte dei commenti salvate e di errori API. Queste metriche tecniche mostrano in quale fase è cambiato il risultato. Una risposta vuota, una richiesta non riuscita e l’assenza di corrispondenze dopo la classificazione tematica sono condizioni diverse: registrale separatamente.
Per il database, conviene separare le entità relative alle raccolte, ai video, alle risposte originali dei commenti e alle decisioni di etichettatura. Il collegamento alla query e al video permette di aprire la fonte per una verifica manuale. Una volta confermato lo schema, puoi aggiungere la paginazione con cursore: l’endpoint accetta cursor e la richiesta successiva deve trasmettere il valore restituito dall’API senza tentare di interpretarlo.
Vantaggi di questo approccio
Il team ottiene un processo di raccolta ripetibile e un insieme di fonti verificabili da cui costruire una coda di temi. L’analista può risalire dalla query di ricerca al video e alla risposta dei commenti salvata. Dopo aver verificato la struttura, chi sviluppa potrà aggiungere la normalizzazione e il raggruppamento tematico senza basarsi su supposizioni riguardo a uno schema sconosciuto.
Nel report, indica le frasi di ricerca, la data di esecuzione, i criteri di selezione e il numero di risposte elaborate. Le conclusioni si riferiscono alle query specifiche e ai dati restituiti; aiutano a esaminare le conversazioni individuate e a pianificare le verifiche, mantenendone provenienza e contesto.
Inizia con un prodotto e alcune query diagnostiche: salva le risposte, verifica la struttura dei commenti e aggiungi al normalizzatore soltanto i campi confermati. I parametri degli endpoint sono descritti nella documentazione dell’API, mentre le informazioni sul prodotto sono disponibili nella pagina TikTok Scraper API.