jsonscraper
Mercati
Torna al diario

Come trasformare la ricerca TikTok in un registro settimanale delle modifiche

Uno script Python salva i nuovi video trovati, li confronta tramite ID e genera un CSV per il monitoraggio periodico degli argomenti

Politica editoriale Segnala un errore

Un report settimanale delle ricerche su TikTok è utile quando mostra quali video sono comparsi nel nuovo insieme di risultati rispetto all’esecuzione precedente. Per ottenerlo basta salvare gli identificativi dei video già incontrati e aggiungere al CSV i nuovi risultati. Di seguito trovi uno script Python riproducibile con TikTok Scraper API: cerca video per parola chiave, analizza entrambe le strutture di risposta documentate e mantiene un database locale di ID.

Obiettivo: individuare i nuovi contenuti, senza riesaminare tutti i risultati

Un team di assistenza, un ricercatore di mercato o un analista dei contenuti può avere bisogno di raccogliere regolarmente video pubblici che corrispondono a una query su un prodotto. Se ogni volta si esporta l’intero risultato, i video ripetuti rendono più difficile la revisione e i nuovi contenuti rischiano di perdersi tra quelli già esaminati. Un registro degli identificativi consente di confrontare i risultati di ogni esecuzione: il CSV contiene solo i video nuovi per questo processo e i principali campi restituiti nella risposta.

Questo registro risponde a una domanda circoscritta ma pratica: quali elementi sono comparsi nella risposta dell’esecuzione corrente e non erano presenti nell’insieme di ID salvato? È utile per creare una coda di revisione manuale e trasferire i dati in un foglio di calcolo o in un’analisi successiva. La raccolta riflette i risultati dell’API per la query specificata; da sola non descrive tutte le pubblicazioni su TikTok.

Requisiti

  • Python 3.8 o versione successiva.
  • Accesso a TikTok Scraper API e una chiave di licenza.
  • Una query che possa essere ripetuta senza modificarne il significato, ad esempio il nome di un prodotto o una frase specifica.

Salva la chiave nella variabile d’ambiente JSONSCRAPER_TIKTOK_LICENSE_KEY, non nel file dello script. Nell’esempio seguente la chiave viene passata come parametro di richiesta license_key, secondo lo schema dell’API. Non mostrarla nei log di esecuzione.

export JSONSCRAPER_TIKTOK_LICENSE_KEY="la_tua_chiave"
python -m pip install requests

In Windows PowerShell, puoi impostare la variabile per la sessione corrente così: $env:JSONSCRAPER_TIKTOK_LICENSE_KEY="la_tua_chiave". Non inserire segreti reali in Git o in un CSV condiviso.

Integrazione: eseguire la ricerca e normalizzare il JSON

Per cercare video, la documentazione descrive l’endpoint GET /searchVideo con il parametro obbligatorio keyword. La richiesta può includere anche count, una regione, un ordinamento, un filtro temporale e un cursore per scorrere i risultati. Questo esempio minimo usa solo la parola chiave, il numero di elementi da richiedere e la regione Stati Uniti. Il riferimento degli endpoint TikTok API elenca i nomi esatti dei parametri.

La struttura della risposta di ricerca merita particolare attenzione: l’array aweme_list può essere vuoto, mentre gli elementi video possono trovarsi in search_item_list, con i dati annidati in aweme_info. Perciò il codice controlla entrambi i percorsi, quindi unisce gli elementi ed elimina i duplicati tramite aweme_id. In questo modo si evita che un JSON analizzato correttamente produca per errore un report vuoto.

import csv
import json
import os
from pathlib import Path
from datetime import datetime, timezone

import requests

BASE_URL = "https://tiktok.evelode.com/searchVideo"
KEYWORD = "nome del prodotto"
REGION = "US"
COUNT = 30
STATE_FILE = Path("seen_video_ids.json")
OUTPUT_FILE = Path("new_tiktok_videos.csv")

license_key = os.environ.get("JSONSCRAPER_TIKTOK_LICENSE_KEY")
if not license_key:
    raise RuntimeError("Imposta JSONSCRAPER_TIKTOK_LICENSE_KEY")

response = requests.get(
    BASE_URL,
    params={
        "license_key": license_key,
        "keyword": KEYWORD,
        "count": COUNT,
        "region": REGION,
    },
    timeout=60,
)
response.raise_for_status()
data = response.json()

# La risposta di esempio contiene status esterno e un oggetto tiktok annidato.
if "status" in data and data["status"] != "ok":
    raise RuntimeError("L’API ha restituito uno status diverso da ok")

tiktok = data.get("tiktok") or {}
items = list(tiktok.get("aweme_list") or [])
for entry in tiktok.get("search_item_list") or []:
    info = entry.get("aweme_info")
    if isinstance(info, dict):
        items.append(info)

# Elementi unici nella risposta corrente, mantenendo l’ordine.
current = {}
for item in items:
    video_id = item.get("aweme_id")
    if video_id:
        current[str(video_id)] = item

if STATE_FILE.exists():
    seen = set(json.loads(STATE_FILE.read_text(encoding="utf-8")))
else:
    seen = set()

new_items = [(video_id, item) for video_id, item in current.items()
             if video_id not in seen]
run_time = datetime.now(timezone.utc).isoformat()

fields = ["collected_at_utc", "query", "aweme_id", "created_at",
          "author", "description", "share_url", "play_count",
          "digg_count", "comment_count", "share_count"]
write_header = not OUTPUT_FILE.exists() or OUTPUT_FILE.stat().st_size == 0
with OUTPUT_FILE.open("a", newline="", encoding="utf-8") as f:
    writer = csv.DictWriter(f, fieldnames=fields)
    if write_header:
        writer.writeheader()
    for video_id, item in new_items:
        author = item.get("author") or {}
        stats = item.get("statistics") or {}
        writer.writerow({
            "collected_at_utc": run_time,
            "query": KEYWORD,
            "aweme_id": video_id,
            "created_at": item.get("create_time"),
            "author": author.get("unique_id") or author.get("nickname"),
            "description": item.get("desc"),
            "share_url": item.get("share_url"),
            "play_count": stats.get("play_count"),
            "digg_count": stats.get("digg_count"),
            "comment_count": stats.get("comment_count"),
            "share_count": stats.get("share_count"),
        })

seen.update(current.keys())
STATE_FILE.write_text(json.dumps(sorted(seen)), encoding="utf-8")
print(f"Video unici nella risposta: {len(current)}; nuovi: {len(new_items)}")

Lo script scrive celle vuote per i valori non presenti nel JSON: i campi e le metriche potrebbero mancare in singoli record. Il codice non sostituisce i valori mancanti con zero e non interpreta lo zero come dato assente. L’ora di raccolta è distinta da quella di pubblicazione, restituita dall’API nel campo create_time.

Come funziona il rilevamento delle modifiche

  1. La richiesta restituisce una pagina di risultati di ricerca per la parola chiave specificata.
  2. Il normalizzatore raccoglie i record da aweme_list e search_item_list[].aweme_info.
  3. Lo script elimina i duplicati presenti nella risposta usando l’ID del video.
  4. Gli identificativi vengono confrontati con il registro JSON locale.
  5. I nuovi ID vengono aggiunti al CSV, quindi l’intero insieme rilevato viene salvato per l’esecuzione successiva.
Articolo: Come trasformare la ricerca TikTok in un registro settimanale delle modifiche
Sommario: Imposta una raccolta ripetibile di video TikTok tramite una query: gestisci entrambe le strutture di risposta dell’API, elimina i duplicati e salva solo i nuovi risultati per il report settimanale.
Ruolo dell’immagine: illustrazione di supporto 2 — un aspetto specifico diverso
Sezione: Come funziona il rilevamento delle modifiche
Soggetto visivo: Infografica chiara in russo che mostra cinque fasi verificate del flusso di lavoro con etichette: Richiesta / Due array di risposta / Deduplicazione per awe
Lo schema mostra il percorso dalla risposta della ricerca al CSV dei nuovi record e al registro JSON per l’esecuzione successiva.© jsonscraper · illustrazione generata dall’IA
Articolo: Come trasformare la ricerca TikTok in un registro settimanale delle modifiche
Sommario: Imposta una raccolta ripetibile di video TikTok tramite una query: gestisci entrambe le strutture di risposta dell’API, elimina i duplicati e salva solo i nuovi risultati per il report settimanale.
Ruolo dell’immagine: copertina — l’idea centrale
Sezione: Come funziona il rilevamento delle modifiche
Soggetto visivo: Natura morta editoriale dedicata alla revisione settimanale dei dati: schede trasparenti sovrapposte che rappresentano i risultati di una ricerca di video brevi pubblici, con una nuova scheda accanto a un compatt
Gli identificativi nuovi per il registro locale vengono separati dai video già rilevati.© jsonscraper · creato con IA

Visualizzare questo processo può essere utile quando si passa lo script ai colleghi: il CSV è un registro incrementale, mentre il JSON contiene lo stato usato per la deduplicazione. È possibile conservarli separatamente dal codice ed eseguirne il backup insieme. Per un’esecuzione di squadra o nel cloud, sostituisci il file JSON locale con uno storage persistente adeguato e prevedi un aggiornamento atomico dello stato, così le esecuzioni parallele non si sovrascrivono a vicenda.

Esecuzioni successive e paginazione

Ripeti l’esecuzione secondo una pianificazione tramite lo scheduler del sistema operativo, un’attività CI o un flusso di automazione. Non modificare la parola chiave senza registrarne la versione: query diverse producono insiemi di risultati differenti e combinarle nello stesso registro ne complica l’interpretazione. Per semplicità, lo script riportato usa una sola query; puoi elaborare un elenco di query con un ciclo, mantenendo il campo query per ogni riga.

L’API supporta cursor per scorrere i risultati della ricerca. Se aggiungi la paginazione, passa il cursore della risposta precedente, conservalo come valore opaco e interrompi la scansione quando non servono altre pagine. Il limite count specifica quanti elementi richiedere, ma il numero effettivo di record va determinato in base alla risposta. Anche più pagine restano pagine ottenute dalla ricerca, non garantiscono una copertura completa della piattaforma.

Questo scenario non include intenzionalmente classificazione automatica del testo né conclusioni su una «tendenza». Il CSV aiuta a individuare rapidamente i nuovi contenuti trovati; un analista può poi etichettarli per argomento, intenzione o tipo di domanda e verificare manualmente alcuni esempi. Se integri un modello linguistico, inviagli solo i campi testuali necessari e chiedigli di restituire le categorie insieme all’ID originale, così il risultato può essere verificato e collegato al record.

Controlli ed errori comuni

  • Errore HTTP. raise_for_status() interrompe l’esecuzione se il codice HTTP non rientra nell’intervallo di successo. Verifica la disponibilità dell’API, i parametri e l’account prima di aggiornare il file di stato.
  • Lo status dell’API è diverso da ok. Se la risposta contiene un campo di primo livello status con un altro valore, lo script si interrompe prima di scrivere i risultati. In questo modo il registro precedente resta intatto e si evita di scambiare una risposta errata per un risultato vuoto.
  • Elenco vuoto in aweme_list. Controlla anche search_item_list; il codice gestisce entrambe le strutture.
  • I video si ripetono tra le esecuzioni. È normale quando le pagine dei risultati di ricerca si sovrappongono: non vengono aggiunti di nuovo al report se il loro ID è già stato salvato.
  • Una metrica è assente. La cella resta vuota. Nei calcoli, distingui i valori mancanti dagli zeri effettivi.
  • Lo stato è andato perso. Lo script considererà nuovi tutti gli ID restituiti. Esegui il backup di seen_video_ids.json insieme al CSV oppure usa un database persistente.

Quando automatizzi il processo, registra informazioni diagnostiche senza includere la chiave: ora di esecuzione, codice HTTP, status dell’API, numero di record analizzati e numero di nuovi ID. Questo aiuta a distinguere l’assenza di nuovi video da una richiesta non riuscita. Se serve verificare in seguito lo schema, puoi archiviare separatamente la risposta completa originale; limita l’accesso e la durata della conservazione in base alle esigenze del team.

Risultato

Dopo l’esecuzione avrai un CSV con i video identificati da ID nuovi per il registro, le descrizioni, i link e i campi pubblici disponibili, oltre allo stato JSON necessario per il confronto successivo. È un risultato adatto come coda di lavoro compatta per l’assistenza, l’analisi o il team dei contenuti. Puoi consultare la descrizione dell’API e le opzioni di accesso nella pagina TikTok Scraper API; verifica i parametri di ricerca esatti nel riferimento ufficiale degli endpoint.

Persone

Nessuna persona elencata ancora per questo articolo.

Continua a leggereCome individuare le domande ricorrenti su un prodotto su TikTok
Leggi il prossimo articolo

Trasforma ciò che leggi in un'integrazione funzionante

Esplora le API per dati social di jsonscraper, prova le richieste e crea il tuo prossimo flusso di lavoro.

Esplora API