Michael JohnsonUn team di marketing nota la comparsa su TikTok di video dedicati a un nuovo prodotto, ma controllare manualmente ogni giorno diversi hashtag è difficile. Per confrontare le pubblicazioni e le metriche visibili nel tempo, serve una raccolta ripetibile, con data e ora, archivio delle risposte originali e verifica delle modifiche.
Per un prototipo di questo tipo è adatta la TikTok Scraper API di jsonscraper: la pagina del prodotto elenca endpoint per hashtag, utenti, video e ricerca. Il primo passo è verificare in Postman l’endpoint necessario e il formato della risposta, quindi trasferire in Python la configurazione confermata. In questo modo si può creare un processo ripetibile, estraendo soltanto i campi effettivamente presenti nella risposta.
L’obiettivo: osservare l’andamento, non un singolo video popolare
Una pubblicazione con molte visualizzazioni può attirare l’attenzione, ma per pianificare una campagna è più utile capire quanti nuovi video vengono individuati su un argomento e come cambiano le metriche pubbliche delle pubblicazioni già trovate. Per esempio, prima di preparare contenuti creativi a tema, un negozio online di articoli sportivi potrebbe voler valutare il flusso di video dedicati a una particolare disciplina di allenamento.
Il controllo manuale rende difficili i confronti: i risultati cambiano, le metriche aumentano e i dipendenti possono registrarle in formati diversi. Salvando uno snapshot a ogni esecuzione, insieme all’ora di raccolta e al JSON originale, il team ottiene uno storico delle proprie osservazioni e può rielaborare i dati se cambia lo schema di analisi.
L’automazione comprende diversi passaggi: verificare l’endpoint e i parametri, richiedere i dati secondo una pianificazione, salvare la risposta, confermarne la struttura e poi estrarre i campi necessari. La tabella ottenuta può essere utilizzata per grafici, classificazione tematica o report.
Cosa conferma la documentazione dell’API
La pagina della TikTok Scraper API indica l’indirizzo di base https://tiktok.evelode.com ed elenca gli endpoint della categoria Hashtag: GET /getHashtagInfo, GET /getHashtagFeed e GET /getHashtagFeedByID. La pagina mostra anche un esempio di richiesta a un altro endpoint con il parametro license_key e descrive come configurare la chiave nella raccolta Postman.
Per GET /getHashtagFeed, la specifica ufficiale degli endpoint indica il parametro obbligatorio query (URL dell’hashtag o nome del tag) e i parametri facoltativi cursor, count, region e cache_timeout. La risposta del feed dovrebbe contenere l’array tiktok.aweme_list; tra i campi elencati per ogni elemento figurano aweme_id, desc, create_time, share_url, i dati dell’autore e statistics. Alcuni campi potrebbero essere assenti: prima di elaborarli, controlla il JSON effettivamente ricevuto.
La raccolta jsonscraper in Postman permette di eseguire una richiesta di prova, verificare la risposta effettiva e ottenere un esempio di test per i controlli successivi sul codice. Per l’autenticazione si passa license_key; conserva la chiave in una variabile d’ambiente e non inserirla nei log.
Per prima cosa, verifica la richiesta in Postman
Inizia con un hashtag di prova. Nella raccolta seleziona l’endpoint del feed hashtag, imposta license_key nel modo indicato dalla documentazione e passa il nome del tag in query. Se necessario, aggiungi count e il codice del Paese in region. Esegui la richiesta e controlla il codice di stato HTTP, il campo di primo livello status e il contenuto di tiktok.aweme_list.
Salva la risposta riuscita in un file JSON di test. Usalo per verificare la presenza dell’identificativo della pubblicazione, della descrizione, dell’ora di pubblicazione, del link e delle statistiche. Aggiungi un campo allo schema di analisi solo dopo aver verificato che sia restituito con il tipo previsto.
Conserva la chiave API in una variabile d’ambiente, non nel file sorgente. Se la chiave viene passata nell’URL, mascherala nei log delle richieste, così da non registrare l’indirizzo completo.
Client Python per le richieste e l’archiviazione
L’endpoint e i nomi dei parametri riportati qui sotto corrispondono alla specifica pubblicata: per l’hashtag si usa query, mentre l’autenticazione viene trasmessa tramite license_key. L’esempio è compatibile con Python 3.8+ e salva la risposta originale insieme ai metadati dell’esecuzione.
import json
import os
from datetime import datetime, timezone
from pathlib import Path
import requests
BASE_URL = "https://tiktok.evelode.com"
API_KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
def fetch_hashtag_feed(hashtag: str) -> dict:
params = {
"license_key": API_KEY,
"query": hashtag,
"count": 20,
}
response = requests.get(
f"{BASE_URL}/getHashtagFeed",
params=params,
timeout=45,
)
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 archive_response(hashtag: str, payload: dict) -> Path:
collected_at = datetime.now(timezone.utc).isoformat()
safe_tag = hashtag.lstrip("#").replace("/", "_")
output_dir = Path("data/raw") / safe_tag
output_dir.mkdir(parents=True, exist_ok=True)
filename = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ.json")
file_path = output_dir / filename
file_path.write_text(
json.dumps(
{
"hashtag": hashtag,
"collected_at": collected_at,
"response": payload,
},
ensure_ascii=False,
indent=2,
),
encoding="utf-8",
)
return file_path
if __name__ == "__main__":
tag = "#esempiotema"
payload = fetch_hashtag_feed(tag)
saved_path = archive_response(tag, payload)
print(f"Archivio salvato: {saved_path}")
Prima dell’esecuzione, imposta la variabile d’ambiente JSONSCRAPER_TIKTOK_LICENSE_KEY. La richiesta usa il parametro confermato query e limita il numero di elementi richiesti tramite count. La risposta viene verificata a livello HTTP e JSON; l’archivio conserva i dati effettivi per le elaborazioni successive. Prova lo script con un solo hashtag prima di aggiungere la pianificazione e l’analisi.
Come aggiungere la normalizzazione senza supposizioni fragili
La documentazione indica che la risposta del feed contiene l’array tiktok.aweme_list. Prima della conversione, verifica che tiktok sia un oggetto e aweme_list una lista. Per ogni elemento estrai soltanto i campi confermati, per esempio aweme_id, desc, create_time, share_url e i valori di statistics, se presenti.
La tabella interna può contenere l’hashtag della richiesta, l’ora di raccolta, l’identificativo del video e le metriche selezionate. Per un indicatore facoltativo o assente, conserva un valore vuoto: l’assenza di una metrica è diversa da uno zero misurato. Conserva separatamente le risposte originali, così da poter ricostruire la tabella senza inviare una nuova richiesta.
Se il formato della risposta cambia, il controllo dei tipi dovrebbe interrompere l’elaborazione non valida e generare un messaggio diagnostico. Conserva il JSON di test accanto al test del parser: servirà a verificare che la nuova versione del codice continui a gestire lo schema noto.
Metriche basate su osservazioni ripetute
Se la risposta fornisce dei contatori, salva ogni osservazione con un timestamp. Per una singola pubblicazione, confronta i valori di due esecuzioni e calcola la variazione osservata nell’intervallo. Per abbinarle, usa aweme_id, indicato nella specifica, e verificane la presenza in ogni elemento.
Il numero di pubblicazioni individuate per la prima volta in un giorno può essere calcolato sui risultati delle tue esecuzioni. Questa metrica descrive il flusso restituito da specifiche richieste, con determinati parametri e una data pianificazione. Permette di confrontare i tuoi snapshot, purché il metodo di raccolta rimanga coerente.
Un report essenziale può mostrare il numero di nuove pubblicazioni individuate ogni giorno, la distribuzione dei contatori disponibili e la variazione dei valori dei video ritrovati in più rilevazioni. Aggiungi l’ora della richiesta e il nome del file originale, così che l’analista possa verificare la provenienza di ogni record.
Pianificazione e gestione degli errori
Quando la richiesta e l’analisi sono state verificate, esegui lo script secondo una pianificazione, per esempio tramite cron, GitHub Actions o un orchestratore di dati. Sposta l’elenco degli hashtag in una configurazione separata, così da poter aggiungere o rimuovere argomenti senza modificare la logica del client.
Per l’esecuzione automatica, imposta un timeout, un numero limitato di tentativi in caso di errori di rete temporanei e la registrazione del codice di stato HTTP e della durata della richiesta. Non registrare la chiave. In caso di errore di analisi, conserva informazioni diagnostiche non sensibili e avvisa la persona responsabile.
La specifica supporta la paginazione tramite il parametro cursor per il feed hashtag. Se ti serve, conserva il cursore restituito e passalo invariato nella richiesta successiva; elabora soltanto i risultati restituiti e controlla has_more, se presente. Se le richieste per più hashtag restituiscono la stessa pubblicazione, scegli la chiave di deduplicazione in base all’obiettivo: conteggiarla separatamente per ogni hashtag oppure considerare soltanto i video unici.
Classificazione e automazione dei report
Dopo aver ottenuto righe verificate, puoi classificare le descrizioni dei video in base a temi definiti: lo schema dell’elemento indica il campo desc. Un modello può raggruppare le pubblicazioni per formato, ad esempio tutorial, recensioni o esperienze personali. Conserva il testo originale, l’etichetta, la versione delle istruzioni e il risultato; sottoponi i casi dubbi alla verifica di una persona.
Calcola le metriche numeriche con codice ordinario, così che le esecuzioni ripetute producano risultati aritmetici riproducibili. Un classificatore è utile per elaborare il testo; il report finale dovrebbe collegare le conclusioni a righe specifiche e alle date delle osservazioni.
In uno scenario no-code, puoi collegare gli stessi passaggi in uno strumento di automazione: pianificazione, richiesta HTTP con la configurazione verificata, controllo della risposta, salvataggio del JSON, trasformazione dei campi confermati e notifica degli errori. Verifica prima il contratto in Postman, quindi trasferiscilo in Python, n8n o Make.
Risultato atteso e passaggio successivo
Una volta configurato il processo, il team avrà un archivio delle risposte API e una tabella di osservazioni per gli hashtag selezionati. Potranno servire a individuare nuove pubblicazioni, confrontare nel tempo le metriche disponibili e selezionare i contenuti da analizzare più a fondo. Per ottenere risultati confrontabili, mantieni coerenti la pianificazione, i parametri delle richieste e le regole di normalizzazione.
Inizia con un solo endpoint e una risposta reale: esegui una richiesta a /getHashtagFeed con il parametro query, salva il JSON e poi aggiungi l’analisi dei campi e la pianificazione. La pagina della TikTok Scraper API mostra l’indirizzo di base e la mappa degli endpoint, mentre la specifica degli endpoint riporta i nomi dei parametri necessari per implementare il client.