Michael JohnsonSe un team deve verificare come gli autori dichiarano i rapporti con un brand nei video TikTok pubblici, un primo risultato utile non è un verdetto automatico, ma una coda compatta di video con didascalia, link e parole chiave individuate. Ecco un flusso di lavoro pratico: inviare una query di ricerca tramite TikTok Scraper API di jsonscraper, uniformare i due possibili formati della risposta e salvare un CSV da sottoporre alla verifica di uno specialista.
Obiettivo: trovare i video da sottoporre a verifica
È difficile rendere ripetibile una ricerca manuale per nome dell’azienda: i risultati vanno raccolti uno alla volta e i motivi della selezione restano nel browser. Una raccolta automatizzata consente di salvare la query, la data di esecuzione e i contenuti trovati in una tabella, così che il team possa verificare i video usando un elenco uniforme.
In questo scenario, «candidato alla verifica» indica soltanto un video presente nei risultati di ricerca restituiti la cui descrizione contiene una parola o una frase definita in anticipo. Per esempio, potrebbe trattarsi di «pubblicità», «partnership» o «sponsorizzato». Questo filtro testuale aiuta a indirizzare l’attenzione di una persona, ma non valuta il video né stabilisce se siano stati rispettati i requisiti applicabili.
Questa distinzione è importante per un team di marketing. Le raccomandazioni della Federal Trade Commission statunitense descrivono la dichiarazione di un rapporto materiale con un brand come un obbligo che dipende dal contesto del messaggio; per i video, la FTC raccomanda di considerare una dichiarazione visibile e udibile. Una ricerca nelle didascalie può individuare alcuni segnali testuali, ma per decidere occorre guardare la pubblicazione e valutarne il contesto. La guida della FTC per gli autori illustra queste condizioni con alcuni esempi.
Risultato: un CSV con il motivo della selezione
La pipeline registrerà una riga per ogni identificatore video univoco e includerà il testo della descrizione, il link, il nome dell’autore, i contatori pubblici disponibili e gli indicatori corrispondenti. Aggiungeremo anche la query di ricerca originale e l’ora della raccolta. In questo modo la tabella potrà essere inserita in una coda operativa e, in seguito, sarà possibile capire perché un determinato video vi è stato incluso.
Il glossario degli indicatori viene definito da un redattore o da uno specialista di conformità. Iniziate con la lingua e i termini effettivamente usati nella vostra campagna, poi rivedete i risultati e, se necessario, ampliate l’elenco. I valori riportati nel codice seguente sono volutamente semplici: vanno sostituiti in base al brand, al mercato e alla lingua dei contenuti.
Connessione a TikTok Scraper API
La documentazione di jsonscraper indica il percorso GET /searchVideo sull’indirizzo base https://tiktok.evelode.com per la ricerca di video. Il parametro obbligatorio è keyword; tra quelli facoltativi figurano count, date_posted, sort_by e region. La chiave viene passata come license_key, quindi conservatela in una variabile d’ambiente, non nel codice o nel CSV. I nomi esatti dei parametri e il percorso sono riportati nel riferimento agli endpoint TikTok; informazioni sul prodotto e sull’accesso sono disponibili nella pagina di TikTok Scraper API.
C’è una particolarità della risposta che influisce sulla completezza del parser locale: i dati possono trovarsi in tiktok.aweme_list oppure in tiktok.search_item_list[].aweme_info. Per questo lo script controlla entrambi gli array. Se la ricerca restituisce un elenco vuoto, creerà un CSV vuoto, senza sostituire l’assenza di risultati con righe fittizie.
Esempio in Python: ricerca, filtro e CSV
L’esempio usa solo la libreria standard di Python 3.8+. Prima di eseguirlo, impostate nell’ambiente la variabile JSONSCRAPER_TIKTOK_LICENSE_KEY. La richiesta usa keyword e passa la chiave nel parametro di query license_key, come indicato nella specifica.
import csv
import json
import os
import sys
from datetime import datetime, timezone
from urllib.parse import urlencode
from urllib.request import Request, urlopen
API_KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
KEYWORD = "Acme"
MARKERS = ["реклама", "партнерство", "партнёрство", "спонсор", "ad", "sponsored"]
params = {
"license_key": API_KEY,
"keyword": KEYWORD,
"count": 30,
"sort_by": "date-posted",
"date_posted": "this-month",
"region": "US",
}
url = "https://tiktok.evelode.com/searchVideo?" + urlencode(params)
request = Request(url, headers={"Accept": "application/json"})
with urlopen(request, timeout=30) as response:
payload = json.load(response)
if payload.get("status") != "ok":
raise RuntimeError("API returned a non-ok outer status")
tiktok = payload.get("tiktok") or {}
items = list(tiktok.get("aweme_list") or [])
for entry in tiktok.get("search_item_list") or []:
info = entry.get("aweme_info") or {}
if info:
items.append(info)
seen = set()
rows = []
collected_at = datetime.now(timezone.utc).isoformat()
for item in items:
video_id = item.get("aweme_id")
if not video_id or video_id in seen:
continue
seen.add(video_id)
description = item.get("desc") or ""
lowered = description.casefold()
matched = [word for word in MARKERS if word.casefold() in lowered]
if not matched:
continue
author = item.get("author") or {}
stats = item.get("statistics") or {}
rows.append({
"collected_at_utc": collected_at,
"search_keyword": KEYWORD,
"video_id": video_id,
"share_url": item.get("share_url") or "",
"description": description,
"matched_markers": "; ".join(matched),
"author_name": author.get("nickname") or "",
"author_id": author.get("unique_id") or "",
"play_count": stats.get("play_count", ""),
"digg_count": stats.get("digg_count", ""),
"comment_count": stats.get("comment_count", ""),
"share_count": stats.get("share_count", ""),
})
fields = [
"collected_at_utc", "search_keyword", "video_id", "share_url",
"description", "matched_markers", "author_name", "author_id",
"play_count", "digg_count", "comment_count", "share_count",
]
with open("tiktok_review_queue.csv", "w", newline="", encoding="utf-8-sig") as output:
writer = csv.DictWriter(output, fieldnames=fields)
writer.writeheader()
writer.writerows(rows)
print(f"Saved {len(rows)} review candidates to tiktok_review_queue.csv")Lo script controlla prima lo stato esterno, poi legge l’oggetto tiktok e unisce le varianti disponibili dell’array. La deduplicazione per aweme_id evita righe ripetute se lo stesso video compare in entrambi i percorsi della risposta. Le metriche vengono registrate così come sono restituite; i valori mancanti restano vuoti e non vengono trasformati in zeri.
L’esempio usa i parametri documentati per /searchVideo: date_posted ammette il valore this-month, sort_by ammette date-posted e region accetta un codice paese. Il valore di count imposta la dimensione dei risultati richiesti, ma non garantisce un elenco completo delle pubblicazioni. Se si aggiunge la paginazione, conservate il cursore restituito come valore opaco e passatelo nel parametro cursor.
Verifica umana e automazione dell’esecuzione
Consegnate il CSV alla persona responsabile della verifica insieme a brevi istruzioni: aprire il link, guardare il video e valutare il contesto della didascalia, annotare l’esito e aggiungere un commento se l’indicatore è stato trovato con un significato diverso. Per esempio, il filtro automatico non distingue una dichiarazione pubblicitaria da una discussione su come funziona la pubblicità. La verifica umana colma questa lacuna semantica.
Per raccogliere i dati in modo ripetibile, eseguite lo script secondo una pianificazione tramite cron, un pianificatore CI o un orchestratore di attività. Salvate il CSV con la data di esecuzione oppure caricate le righe in una tabella con una chiave univoca composta dall’identificatore del video e dalla data di osservazione. Se vi serve un registro di audit, conservate anche la risposta JSON originale con controlli di accesso: consente di verificare di nuovo la trasformazione e spiegare la provenienza di ogni riga.
In una versione pronta per l’uso, conviene aggiungere la gestione degli errori di rete e HTTP, un limite ai tentativi di ripetizione e una notifica in caso di errore. Non stampate l’URL completo della richiesta: contiene la chiave di accesso. Se il team ha più utenti, è ragionevole conservare il segreto in un gestore dei segreti dell’ambiente di esecuzione e limitare l’accesso ai file risultanti secondo le regole interne.
Cosa offre esattamente questo elenco
Dopo l’esecuzione, il team avrà una selezione riproducibile di video trovati tramite una frase chiave e un motivo esplicito per l’inclusione di ogni candidato nella coda. Dalla tabella si potranno escludere manualmente le corrispondenze non pertinenti, assegnare un responsabile della verifica e raggruppare i risultati per indicatore o autore. Se la raccolta viene eseguita regolarmente, si aggiungerà una cronologia dei video presenti nei risultati restituiti in una determinata data.
Questo approccio è adatto all’individuazione iniziale e all’instradamento dei contenuti, non a formulare automaticamente un giudizio di conformità. È limitato ai risultati di ricerca, alla parola chiave scelta, alle impostazioni della query e agli indicatori testuali. Per verificare una collaborazione specifica, confrontate il video con il brief e le informazioni a disposizione del vostro team, poi valutate il messaggio stesso secondo le regole applicabili.
Per iniziare, verificate la disponibilità attuale e i parametri nella pagina del prodotto TikTok Scraper API e consultate la documentazione ufficiale dell’API per la struttura della risposta e le opzioni di integrazione.
