Michael JohnsonPer selezionare video pubblici di TikTok che menzionano un brand e contengono formulazioni pubblicitarie esplicite, raccogli i risultati di diverse query di ricerca, estrai le didascalie e segnala le parole chiave. Il risultato è un CSV con link e metriche disponibili, cioè una coda da sottoporre a verifica umana, non una valutazione automatica della conformità alle regole.
Questo processo può essere utile a un’agenzia che confronta una campagna con il brief o a un team interno che tiene un elenco di menzioni pubbliche. Aiuta a organizzare i risultati di ricerca e conserva gli elementi che permettono all’analista di decidere quale video aprire e controllare.
Che cosa cercare nei video?
Per verificare la pubblicità, sono importanti il rapporto tra l’autore e il brand e il modo in cui tale rapporto viene dichiarato accanto a una raccomandazione. La guida FTC per gli influencer spiega che un rapporto rilevante può essere finanziario, lavorativo, personale o familiare e che la dichiarazione deve essere evidente e comprensibile. Per una raccomandazione video, la FTC indica che la dichiarazione va inserita nel video stesso, non soltanto nella descrizione. La didascalia è quindi utile per filtrare i risultati, ma da sola non mostra ciò che lo spettatore ha visto o sentito nel video.
Questo script ha un obiettivo più circoscritto: trovare, tra i risultati di ricerca restituiti, i video le cui didascalie contengono frasi legate al brand e possibili indicatori come «pubblicità», «sponsorizzato» o «partnership». Il vocabolario va adattato alla lingua e alla terminologia della campagna. Se un indicatore non compare nella didascalia, apri il video e controllane il contenuto: una corrispondenza testuale non stabilisce se nel video sia presente una dichiarazione.
Come trasformare i risultati di ricerca in una coda di verifica?
Prepara un breve elenco di query: il nome del brand, quello della campagna e la grafia più comune del prodotto. Esegui le query separatamente e conserva le formulazioni insieme ai risultati. In questo modo il team potrà vedere quale query ha trovato il video e ripetere la raccolta, se necessario.
Per la raccolta puoi usare la TikTok Scraper API di jsonscraper. L’endpoint GET documentato /searchVideo si trova all’indirizzo https://tiktok.evelode.com e accetta i parametri keyword, count, date_posted, sort_by, region e cursor. Nella risposta osservata, i dati TikTok contenevano i video in search_item_list[].aweme_info; aweme_list poteva essere vuoto. Il parser seguente controlla entrambe le posizioni.
La chiave viene passata nel parametro license_key. Conservala in una variabile d’ambiente, non nello script o nel repository. La documentazione degli endpoint TikTok riporta i nomi dei parametri di ricerca; per la pagina successiva usa il cursor restituito. Registra il numero di oggetti elaborati e la query di ricerca: la paginazione permette di proseguire tra i risultati, ma da sola non ne garantisce la completezza.
Esempio essenziale in Python
Lo script esegue una richiesta per ogni frase, raccoglie entrambe le forme documentate dei risultati, elimina i duplicati in base all’ID del video, segnala le parole nella descrizione e scrive un CSV. Installa requests con il comando python -m pip install requests, imposta JSONSCRAPER_TIKTOK_LICENSE_KEY nell’ambiente ed esegui il file. L’esempio è compatibile con Python 3.8 e versioni successive.
import csv
import os
import sys
import requests
BASE_URL = "https://tiktok.evelode.com/searchVideo"
KEY = os.environ.get("JSONSCRAPER_TIKTOK_LICENSE_KEY")
if not KEY:
raise SystemExit("Set JSONSCRAPER_TIKTOK_LICENSE_KEY first")
QUERIES = ["Example Brand", "Example Product", "Example Campaign"]
MARKERS = ("#реклама", "реклама", "спонсор", "партнерство", "партнёрство", "#ad", "sponsored")
def videos_from(payload):
data = payload.get("tiktok") or {}
videos = data.get("aweme_list") or []
if not videos:
videos = [
item.get("aweme_info")
for item in (data.get("search_item_list") or [])
if isinstance(item, dict) and isinstance(item.get("aweme_info"), dict)
]
return [video for video in videos if isinstance(video, dict)]
rows = {}
for query in QUERIES:
response = requests.get(
BASE_URL,
params={"keyword": query, "count": 20, "date_posted": "this-month", "license_key": KEY},
timeout=30,
)
response.raise_for_status()
payload = response.json()
if payload.get("status") != "ok":
print("Unexpected API status for query:", query, file=sys.stderr)
continue
for video in videos_from(payload):
video_id = video.get("aweme_id")
if not video_id:
continue
author = video.get("author") or {}
stats = video.get("statistics") or {}
caption = video.get("desc") or ""
matched = [word for word in MARKERS if word in caption.casefold()]
row = rows.setdefault(str(video_id), {
"video_id": str(video_id),
"url": video.get("share_url") or "",
"author": author.get("unique_id") or author.get("nickname") or "",
"caption": caption,
"queries": set(),
"disclosure_markers": set(),
"play_count": stats.get("play_count"),
"digg_count": stats.get("digg_count"),
"comment_count": stats.get("comment_count"),
"review_status": "manual_review",
})
row["queries"].add(query)
row["disclosure_markers"].update(matched)
with open("tiktok_disclosure_review.csv", "w", newline="", encoding="utf-8-sig") as file:
fields = ["video_id", "url", "author", "caption", "queries", "disclosure_markers",
"play_count", "digg_count", "comment_count", "review_status"]
writer = csv.DictWriter(file, fieldnames=fields)
writer.writeheader()
for row in rows.values():
row["queries"] = " | ".join(sorted(row["queries"]))
row["disclosure_markers"] = " | ".join(sorted(row["disclosure_markers"]))
writer.writerow(row)
print("Saved", len(rows), "unique returned videos")Prima di salvare il codice, controlla lo stato della risposta esterna e poi i dati in tiktok. Il normalizzatore legge entrambe le posizioni dei video. Per la pagina successiva puoi passare il cursor ricevuto alla richiesta successiva senza modificarlo; questo esempio essenziale si limita intenzionalmente a una pagina per query.
Che cosa mostra il CSV?
Ogni riga associa l’ID e il link del video, l’identificativo dell’autore disponibile, la didascalia, le frasi di ricerca e gli indicatori trovati. Se la risposta contiene metriche di visualizzazioni, «mi piace» e commenti, vengono conservate come contesto per stabilire l’ordine delle verifiche. Questi campi potrebbero mancare: lo script li lascia vuoti anziché sostituirli con zeri.
Apri quindi il video, verifica se la dichiarazione è presente e visibile al suo interno e registra il risultato usando categorie concordate, per esempio «trovata», «richiede un’ulteriore verifica» o «non rilevata durante la visione». Il codice cerca soltanto indicatori testuali esatti nella didascalia: non analizza immagini né audio e non decide se il contenuto sia conforme alle regole.
Per un processo ricorrente, programma la raccolta, registra l’ora della richiesta e conserva il JSON originale insieme al CSV. Limita l’elenco di query alle frasi necessarie e definisci un periodo di conservazione per i dati raccolti. La politica di raccolta responsabile dei dati di jsonscraper raccomanda una frequenza ragionevole delle richieste, la minimizzazione dei dati e la verifica dei risultati dell’IA prima di intraprendere azioni successive.
Il risultato è una coda riproducibile di video pubblici da sottoporre a verifica manuale delle dichiarazioni pubblicitarie: le corrispondenze di ricerca e le metriche disponibili aiutano a decidere da quale video iniziare, mentre la valutazione del video stesso resta affidata a chi lo esamina. Puoi verificare i nomi dei parametri nella documentazione dell’API TikTok e consultare le informazioni sul prodotto nella pagina della TikTok Scraper API.
