Come non perdere i risultati di ricerca TikTok analizzando JSON

Quando si cercano video su TikTok tramite API, i video potrebbero non trovarsi nell’array che il parser si aspetta di trovare per primo. In una risposta verificata di jsonscraper alla richiesta `/searchVideo`, il campo `aweme_list` era vuoto, mentre gli elementi contenenti i dati dei video si trovavano in `search_item_list[].aweme_info`. Se il codice legge solo `aweme_list`, salverà zero video anche se la risposta contiene risultati. Per chi sviluppa, si tratta di un problema concreto di affidabilità: estrarre entrambe le forme di dati e normalizzarle in un unico elenco prima di salvarle nel database o inserirle in un report.

È possibile verificare un esempio reale e la descrizione dell’endpoint consultando la specifica dell’API jsonscraper e la documentazione dell’endpoint TikTok. Lo schema nella specifica è datato 25 ottobre 2026: illustra la struttura di una risposta specifica, ma non garantisce che ogni campo sia presente in tutte le richieste successive.

Perché il parser può restituire un elenco vuoto

L’endpoint `GET https://tiktok.evelode.com/searchVideo` cerca video in base al parametro obbligatorio `keyword`. La documentazione elenca anche `cursor`, `count`, `cache_timeout`, `date_posted`, `sort_by` e `region`. Nello schema della risposta osservata, l’oggetto di primo livello contiene `status` e un oggetto annidato `tiktok`; al suo interno si trovano `cursor`, `has_more`, `status_code`, `aweme_list` e `search_item_list`.

Nell’osservazione specifica relativa a una richiesta con una parola chiave e `count=3`, l’array `aweme_list` era vuoto. Allo stesso tempo, `search_item_list` includeva elementi con le informazioni sui video contenute in `aweme_info`. Questi oggetti potevano includere l’ID del video, la didascalia, l’URL della pubblicazione, l’autore e statistiche come il numero di visualizzazioni, «Mi piace» o commenti. I campi descritti rispecchiano lo schema osservato; il parser deve comunque tollerare valori assenti.

La conclusione pratica è che una richiesta HTTP riuscita e la presenza di un array non vuoto in uno specifico campo previsto sono due verifiche diverse. Controllate prima lo stato esterno e la presenza di `tiktok`, quindi raccogliete i video da ogni posizione documentata. Per l’analisi, conservate gli ID e la risposta originale: sarà così possibile ricostruire come è stato estratto e normalizzato uno specifico elemento.

Normalizzate la risposta prima di salvarla

Una funzione che riceve l’oggetto annidato `tiktok` e restituisce elementi uniformi costituisce un utile confine tra l’API e il vostro sistema. Dovrebbe elaborare entrambi gli array, ignorare gli elementi che non sono dizionari o che sono vuoti e rimuovere i video duplicati in base a `aweme_id`. Lasciate vuoti i contatori quando il fornitore non li restituisce: zero indica un valore misurato, mentre `None` segnala che il campo è assente.

Di seguito un esempio minimo per Python 3.8+. Effettua una richiesta, verifica lo stato del trasporto e quello di primo livello, normalizza le due varianti del risultato e stampa i campi selezionati. La chiave viene letta da una variabile d’ambiente e non viene stampata nei log.

import os
import requests

BASE_URL = "https://tiktok.evelode.com"


def extract_videos(tiktok):
    candidates = []
    aweme_list = tiktok.get("aweme_list") or []
    if isinstance(aweme_list, list):
        candidates.extend(aweme_list)

    search_items = tiktok.get("search_item_list") or []
    if isinstance(search_items, list):
        for item in search_items:
            if isinstance(item, dict):
                candidates.append(item.get("aweme_info"))

    unique = {}
    for video in candidates:
        if not isinstance(video, dict):
            continue
        video_id = video.get("aweme_id")
        if video_id:
            unique[video_id] = video
    return list(unique.values())


license_key = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
response = requests.get(
    BASE_URL + "/searchVideo",
    params={
        "license_key": license_key,
        "keyword": "python tutorial",
        "count": 10,
        "region": "US",
    },
    timeout=30,
)
response.raise_for_status()
payload = response.json()

if payload.get("status") != "ok":
    raise RuntimeError("TikTok API returned a non-ok status")

tiktok = payload.get("tiktok")
if not isinstance(tiktok, dict):
    raise RuntimeError("Response has no tiktok object")

for video in extract_videos(tiktok):
    stats = video.get("statistics") or {}
    author = video.get("author") or {}
    print({
        "aweme_id": video.get("aweme_id"),
        "desc": video.get("desc"),
        "share_url": video.get("share_url"),
        "author": author.get("unique_id"),
        "play_count": stats.get("play_count"),
        "digg_count": stats.get("digg_count"),
        "comment_count": stats.get("comment_count"),
    })

Installate la dipendenza con il comando python -m pip install requests, impostate `JSONSCRAPER_TIKTOK_LICENSE_KEY` nell’ambiente di esecuzione e salvate il file, per esempio, come `search_videos.py`. I parametri della richiesta corrispondono ai nomi documentati: `keyword`, `count` e `region`; `license_key` viene passato come parametro della query. Il codice presuppone che la risposta contenga `status: "ok"`, come nell’esempio registrato. Se l’API restituisce uno stato diverso, l’elaborazione si interrompe prima di passare oltre una struttura dubbia.

Come trasformare l’esempio in una raccolta ripetibile

Per un’esportazione una tantum, è sufficiente scrivere gli elementi normalizzati in JSON Lines o in una tabella. In un processo continuativo, aggiungete il salvataggio della risposta originale con l’ora di acquisizione e la query di ricerca. La tabella separata dei video normalizzati può usare `aweme_id` come chiave: un risultato ripetuto aggiorna il record, mentre lo stesso ID presente in entrambi gli array non crea duplicati.

Per richiedere la pagina successiva, la documentazione indica il parametro `cursor`: passate il valore ricevuto nella risposta precedente. Trattatelo come un token opaco, conservandolo e restituendolo senza modifiche. Il ciclo di paginazione dovrebbe terminare quando `has_more` indica che non ci sono altre pagine o quando l’API non fornisce un cursore utilizzabile; limitate il numero di pagine per esecuzione, così da evitare cicli infiniti causati da una logica errata. Le fonti registrate confermano il nome del parametro e la presenza dei campi `cursor` e `has_more` nello schema osservato, ma non garantiscono la completezza dei risultati.

Per monitorare più frasi di ricerca, memorizzate la frase insieme all’ID del video e all’ora di raccolta. Potrete così creare viste per query, confrontare i risultati tra un’esecuzione e l’altra e inviare nuovi ID a una coda per la classificazione successiva. Un sistema del genere descrive i risultati di ricerca ottenuti; il dataset dipende dalla query, dalla regione, dall’ora e dagli elementi effettivamente restituiti dall’API.

Verificate la qualità dei dati, non solo l’esito della richiesta

Dopo la normalizzazione, è utile registrare semplici metriche tecniche della pipeline: numero di record provenienti da ciascun array, numero di ID univoci, percentuale di elementi senza ID e percentuale di elementi senza statistiche. Sono metriche relative all’elaborazione di una specifica risposta, non stime della popolarità dei video. Per esempio, se aumenta il numero di elementi senza `play_count`, l’analisi dovrebbe conservare il valore come sconosciuto e segnalarne l’assenza, anziché sostituirlo con zero.

Non vincolate i calcoli successivi all’ipotesi che ogni video abbia lo stesso insieme di statistiche. Per conservare i dati grezzi, mantenete l’intero JSON; per la tabella analitica, selezionate solo i campi necessari e accettate valori `NULL`. Se la forma della risposta cambia, l’archivio originale permetterà di eseguire di nuovo il normalizzatore senza una nuova richiesta.

Passate la chiave API tramite i secret della CI o le variabili d’ambiente dell’orchestratore. Non includetela negli URL salvati nei log, non stampate l’oggetto dei parametri della richiesta e non memorizzate la chiave insieme alle risposte originali. Se il processo viene eseguito secondo una pianificazione, aggiungete un limite di tempo per la richiesta, la gestione degli errori HTTP e tentativi successivi con una pausa; conservate il cursore insieme alla specifica query di ricerca, per non mescolare le pagine di risultati diversi.

Risultato: una tabella unificata invece di video mancanti

Dopo la normalizzazione, il codice downstream riceve un unico elenco di video, indipendentemente dal fatto che un elemento provenga da `aweme_list` o da `search_item_list[].aweme_info`. L’ID consente di eliminare i duplicati e i campi facoltativi restano esplicitamente vuoti. Si riduce così il rischio di report vuoti causati dalla lettura di un solo array e si rende più prevedibile la fase successiva, che si tratti di esportazione, filtraggio o classificazione.

Per iniziare la verifica, potete consultare la pagina di TikTok Scraper API, che indica l’endpoint API di base e offre un accesso alla demo. Per l’integrazione, usate la documentazione ufficiale e verificate prima l’elaborazione con pochi elementi; se necessario, aumentate `count` e continuate la paginazione usando il cursore documentato. Otterrete un livello di dati ordinato per le vostre attività, senza presumere una copertura completa di TikTok.