Michael JohnsonDopo il lancio di una campagna, può essere utile per il team verificare quali video pubblici compaiono nei risultati di ricerca per i termini scelti. Le ricerche manuali sono difficili da ripetere e confrontare dopo alcuni giorni. Un piccolo script di raccolta può eseguire le stesse query secondo una pianificazione e archiviare le risposte con la data e la frase di ricerca, così che un analista possa controllare i record e preparare un riepilogo personalizzato.
Questa guida mostra una pipeline di archiviazione in Python per salvare i risultati di ricerca di frasi prestabilite. A differenza del monitoraggio di singoli hashtag o account, qui il confronto si basa sulla ripetizione delle stesse frasi e sul salvataggio di un’istantanea separata per ogni risposta. La pagina TikTok Scraper API di jsonscraper indica l’indirizzo di base e l’endpoint GET /searchVideo; nella documentazione dell’endpoint la frase di ricerca viene trasmessa tramite il parametro obbligatorio keyword.
Obiettivo e limiti della misurazione
Immaginiamo che un addetto al marketing voglia raccogliere ogni giorno i risultati per alcune frasi prestabilite: il nome di un prodotto, una categoria e la formulazione di un problema dei clienti. Per ogni richiesta, il sistema salva l’ora della raccolta e la risposta dell’API. Dopo aver verificato un esempio di risposta, è possibile aggiungere la normalizzazione dei campi effettivamente presenti nel JSON, come l’identificativo del video o i contatori pubblici, se disponibili.
L’archivio risponde a una domanda precisa: quali record ha restituito la ricerca per la frase salvata durante questa esecuzione? Se la risposta contiene metriche, osservazioni ripetute possono mostrare la differenza tra i valori registrati in momenti diversi. Tale differenza riguarda le istantanee osservate e l’intervallo che le separa; per poterle confrontare, salva entrambe le date di raccolta e lo stesso campo.
Salva la richiesta insieme alla risposta. I risultati dipendono dalla frase di ricerca specifica e dal momento della raccolta. L’archivio è quindi utile per seguire i risultati delle query selezionate, non come panoramica completa di tutti i contenuti di TikTok. Gli identificativi, le risposte originali e le marche temporali aiutano a verificare l’origine di ogni riga della tabella successiva.
Verifica l’endpoint e i relativi parametri
La mappa degli endpoint dell’API TikTok indica l’indirizzo di base https://tiktok.evelode.com e GET /searchVideo. La specifica API aggiornata definisce keyword come parametro di ricerca obbligatorio; tra quelli facoltativi elenca cursor, count, cache_timeout, date_posted, sort_by e region. Per l’autenticazione si passa license_key. I dettagli dell’endpoint sono disponibili anche nella documentazione dell’SDK Python.
I parametri count e date_posted consentono di definire la dimensione della risposta e il filtro temporale; sort_by accetta i valori documentati most-liked, relevance o date-posted. Se usi la paginazione, trasmetti il cursor ricevuto nella risposta precedente come valore opaco, senza calcolarlo autonomamente. Per mantenere confrontabile l’archivio giornaliero, salva i parametri della richiesta e la versione del tuo codice insieme ai dati.
L’esempio seguente usa un valore basso di count per un test e imposta la regione US. Prima di avviare la raccolta giornaliera, verifica una richiesta, il relativo stato HTTP e la struttura JSON. Lo schema della risposta può contenere i video trovati in tiktok.aweme_list oppure in tiktok.search_item_list, dove l’oggetto video si trova in aweme_info; il codice gestisce entrambe le forme osservate.
Prepara il progetto
Crea un ambiente virtuale e installa requests:
python -m venv .venv
source .venv/bin/activate
pip install requestsIn PowerShell, l’ambiente si attiva con il comando .venv\Scripts\Activate.ps1. Imposta la chiave e l’elenco delle frasi di ricerca tramite variabili d’ambiente. Per l’API TikTok usa il nome documentato della variabile JSONSCRAPER_TIKTOK_LICENSE_KEY:
export JSONSCRAPER_TIKTOK_LICENSE_KEY="la_tua_chiave"
export TIKTOK_QUERIES="nome prodotto,categoria prodotto,problema cliente"Raccolta e salvataggio delle istantanee
L’esempio invia una richiesta per ogni frase all’endpoint documentato, quindi salva il JSON originale, l’ora della raccolta e i parametri utilizzati. Il nome del file include la data e la frase di ricerca. La chiave resta nell’ambiente e non viene inclusa nell’archivio.
import json
import os
import re
import time
from datetime import datetime, timezone
from pathlib import Path
import requests
BASE_URL = "https://tiktok.evelode.com"
ENDPOINT = "/searchVideo"
LICENSE_KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
QUERIES = [
item.strip()
for item in os.environ["TIKTOK_QUERIES"].split(",")
if item.strip()
]
OUT = Path("data")
OUT.mkdir(exist_ok=True)
def safe_name(text):
cleaned = re.sub(r"[^a-zA-Z0-9_-]+", "_", text).strip("_")
return cleaned[:80] or "query"
def fetch(query):
params = {
"license_key": LICENSE_KEY,
"keyword": query,
"count": 10,
"region": "US",
}
response = requests.get(
BASE_URL + ENDPOINT,
params=params,
timeout=60,
)
response.raise_for_status()
payload = response.json()
if payload.get("status") != "ok":
raise RuntimeError("L’API ha restituito uno stato diverso da ok")
return payload
def extract_videos(payload):
tiktok = payload.get("tiktok") or {}
videos = list(tiktok.get("aweme_list") or [])
for item in tiktok.get("search_item_list") or []:
video = item.get("aweme_info") or {}
if video:
videos.append(video)
return videos
for query in QUERIES:
collected_at = datetime.now(timezone.utc).isoformat()
payload = fetch(query)
record = {
"collected_at": collected_at,
"query": query,
"request": {
"endpoint": ENDPOINT,
"keyword": query,
"count": 10,
"region": "US",
},
"videos_found": len(extract_videos(payload)),
"payload": payload,
}
filename = OUT / f"{collected_at[:10]}_{safe_name(query)}.json"
filename.write_text(
json.dumps(record, ensure_ascii=False, indent=2),
encoding="utf-8",
)
print(f"Risposta salvata per la query: {query}")
time.sleep(1)
print(f"Risposte salvate: {len(QUERIES)}")Questo script essenziale invia una richiesta per frase con count=10. Per raccogliere più risultati, aggiungi la paginazione tramite cursor: continua le richieste passando il valore del cursore restituito dall’API finché questa indica che sono disponibili altri risultati e registra separatamente ogni risposta. Il cursore e il numero di risultati definiscono la singola esecuzione; il JSON salvato consente di verificare in seguito che cosa è stato restituito da ciascuna richiesta.
L’esempio verifica il status esterno, quindi legge l’oggetto tiktok. Raccoglie gli elementi da aweme_list e anche da search_item_list[].aweme_info, se è presente questa forma. I possibili campi di un video includono l’identificativo, la descrizione, l’autore, il link e le statistiche; alcuni campi potrebbero mancare. Salva quindi la risposta completa e, durante la normalizzazione, verifica la presenza di ciascun campo.
L’intervallo di un secondo è una pausa tra le richieste inviate dallo script, non un’affermazione sui limiti del servizio. Configura frequenza e tentativi in base alle condizioni di accesso e alla documentazione. Il parametro cache_timeout è documentato per la ricerca e permette di specificare la durata della cache in secondi; secondo la specifica, il valore 0 disattiva la memorizzazione nella cache. Aggiungilo alla richiesta quando questa impostazione è adatta al tuo caso.
Aggiungi la normalizzazione basata sulla risposta effettiva
Dopo la prima esecuzione, apri il file salvato ed esamina la struttura di payload. La funzione extract_videos dell’esempio raccoglie gli elementi da due posizioni documentate per le forme di risposta. Individua le chiavi esatte dei campi che ti servono per l’analisi. Se un campo manca in un record, registralo come valore assente invece di assegnargli un numero ipotetico.
Per elaborare i dati in seguito, è comodo creare una riga per ogni oggetto trovato, aggiungendo collected_at e query. I campi verificati possono essere salvati in un CSV o in un database, mentre il JSON originale resta nell’archivio. Questa soluzione permette di creare tabelle pratiche e, al tempo stesso, di verificare l’origine di ogni record.
Se l’API restituisce l’identificativo del video, usalo per collegare le osservazioni dello stesso video raccolte in esecuzioni diverse. Conserva ogni osservazione separatamente, senza sovrascrivere i dati precedenti. Se non è disponibile un identificativo stabile, verifica prima quali attributi consentono di associare i record e non dare per scontato che una descrizione testuale identica garantisca una corrispondenza.
Confronta le istantanee e prepara un rapporto
Dopo la normalizzazione, raggruppa i record in base all’identificativo verificato e ordinali per ora di raccolta. Per i campi contatore, puoi calcolare la differenza tra due valori consecutivi con il normale codice. Per esempio, il passaggio da 12.400 a 18.900 significa che il valore del contatore è cambiato di 6.500 tra le due istantanee. Nel rapporto indica le date delle osservazioni e il campo originale, così che chi legge possa verificare il calcolo.
Una struttura utile per la tabella finale include la frase di ricerca, l’identificativo del post, l’ora di raccolta e i campi selezionati della risposta. Puoi raggruppare il riepilogo per query e ordinarlo in base a un contatore verificato. In questo modo il team avrà un elenco verificabile dei record restituiti da esaminare; realizza la tabella o il messaggio in un passaggio separato, dopo aver analizzato lo schema effettivo.
All’inizio conserva i file JSON in locale. Quando la raccolta diventa regolare, trasferisci le righe normalizzate in PostgreSQL o in un archivio analitico, e le risposte originali in uno storage a oggetti, indicando nel nome del file la data e la query. Conservare le risposte originali è particolarmente utile quando aggiorni il parser: puoi rieseguirlo sui dati storici senza interrogare di nuovo l’API.
Programma la raccolta
Per creare un archivio giornaliero, esegui lo script tramite cron o un altro pianificatore disponibile nel tuo ambiente. Per esempio, un’attività può avviare il file Python una volta al giorno, passandogli la chiave e le frasi di ricerca tramite variabili d’ambiente. Prima di usarlo regolarmente, verifica una richiesta, poi l’intero elenco e solo dopo attiva la pianificazione.
Per rendere l’esecuzione affidabile, registra lo stato di ogni richiesta, limita il numero di tentativi in caso di errori temporanei e segnala una raccolta incompleta se una frase non viene elaborata. Non includere la chiave nei messaggi di errore. È inoltre utile separare i file per data e nome della query, così che un’esecuzione ripetuta non sovrascriva l’istantanea precedente.
Scegli la frequenza in base all’obiettivo e al volume delle richieste. Per un riepilogo giornaliero basta un’esecuzione al giorno; raccogliere i dati più spesso ha senso se il team deve seguire i cambiamenti nel corso della giornata. Inizia con un elenco breve di frasi, verifica che i risultati restituiti siano utili e poi amplia la raccolta nel rispetto delle condizioni di accesso e delle regole d’uso dei dati.
Usa l’IA per raggruppare i temi
Una volta verificato lo schema della risposta, puoi inviare alla modello i campi di testo selezionati per raggruppare le descrizioni in categorie predefinite o preparare una bozza di riepilogo. Conserva insieme alla classificazione l’identificativo originale del post, la frase di ricerca e il testo su cui si basa la categoria. In questo modo l’analista potrà risalire dal risultato del modello al record originale.
Calcola con il normale codice le differenze numeriche, l’ordinamento e la deduplicazione. Il modello può essere utile per elaborare il testo e formulare il rapporto; per contatori e marche temporali, usa i dati delle risposte salvate. Separare queste operazioni rende chiara l’origine di ogni conclusione.
Verifica manualmente una parte delle categorie automatiche e conserva le correzioni come esempi di test. Se tipi diversi di post finiscono regolarmente nello stesso gruppo, chiarisci le definizioni delle categorie e ripeti la verifica. Questo processo aiuta a valutare la qualità della classificazione sui dati del tuo caso d’uso.
In sintesi: un archivio ripetibile e un riepilogo verificabile
Dopo aver avviato la richiesta documentata con il parametro keyword, il team dispone di un archivio che registra quali frasi sono state usate, quando è avvenuta la raccolta e quali dati l’API ha restituito per ciascuna. Su questa base è possibile creare una tabella dei risultati, confrontare i campi verificati tra diverse istantanee e preparare un elenco dei post trovati da esaminare manualmente.
Inizia con una richiesta di prova, poi configura l’elenco delle frasi e la pianificazione. La descrizione della TikTok Scraper API riporta l’indirizzo di base e la mappa degli endpoint; i parametri di /searchVideo e la forma della risposta sono descritti nella specifica API. Archiviare le risposte verificate crea una base per un’analisi ripetibile basata su frasi di ricerca prestabilite.