Michael JohnsonUn professionista del marketing può trovare su TikTok un video il cui autore parla di un prodotto di interesse, ma passare da questo segnale a un contatto verificabile è più difficile: il nome dell’autore su TikTok e quello su IG possono essere diversi, e il profilo potrebbe essere privato o non avere alcun collegamento confermato con una persona. Il risultato pratico non è un elenco automatico di «lead pronti», ma una tabella di verifiche: video originale, autore TikTok, username IG ipotizzato, risposta dell’API e stato per l’analisi successiva.
Di seguito trovi un processo Python essenziale per questo compito. Cerca video pubblici in base a una frase chiave, estrae i dati disponibili sull’autore e verifica i profili IG solo se hai già un username fondato da controllare. L’API può recuperare i dati di un profilo tramite username; non stabilisce automaticamente che due account appartengano alla stessa persona.
Quale risultato conviene automatizzare
Immagina un team che vende attrezzature per il caffè preparato in casa e vuole trovare autori di video pubblici sulla preparazione di bevande. La ricerca manuale è utile per una prima ricognizione dei contenuti, ma quando viene ripetuta è difficile ricordare quale video ha portato al contatto, da dove proviene il nome del profilo e che cosa è stato effettivamente verificato.
La pipeline separa tre attività: cercare video su TikTok, salvare i dati osservabili e verificare il profilo IG ipotizzato. In questo modo l’analista può aprire un unico file CSV e vedere la provenienza di ogni candidato. I campi IG andrebbero compilati solo dopo aver trovato lo username in una descrizione pubblica o in un link dell’autore, oppure dopo averlo verificato manualmente sulla base di altro materiale disponibile.
Questo approccio è utile per un’agenzia, un gruppo di ricerca o un professionista del marketing interno che ha bisogno di un piccolo elenco riproducibile da qualificare manualmente. Conserva il contesto della scoperta e non trasforma la somiglianza tra nomi in un’affermazione di identità.
Quali campi si possono ottenere
L’endpoint documentato di TikTok /searchVideo richiede il parametro keyword; sono disponibili anche count, date_posted, sort_by, region e cursor. Nelle risposte osservate compaiono l’ID del video, la descrizione, la data di pubblicazione, il link, i dati dell’autore e i conteggi pubblici delle interazioni. I campi effettivamente presenti possono variare, quindi il codice seguente usa letture sicure e valori vuoti.
Per IG, questo esempio usa l’endpoint GET documentato /v1/user/by/username con il parametro username. La risposta può includere username, nome visualizzato, stato di privacy e verifica, numero di pubblicazioni, follower e account seguiti, oltre alla biografia. Si tratta di informazioni da esaminare e valutare in seguito, non di un punteggio attribuito all’autore.
La documentazione ufficiale dell’API TikTok descrive i parametri di ricerca, mentre la documentazione dell’API IG illustra metodi e parametri di IG. Anche le definizioni integrate delle API jsonscraper specificano gli endpoint, i nomi dei parametri e le forme di risposta osservate; i controlli riportati sono del 25 ottobre 2026.
Configura le chiavi e l’elenco dei candidati
Salva le chiavi API nelle variabili d’ambiente: JSONSCRAPER_TIKTOK_LICENSE_KEY e JSONSCRAPER_INSTAGRAM_LICENSE_KEY. Non inserirle nel codice sorgente, nei file CSV o nei log dei processi. Per installare la libreria per le richieste, usa python -m pip install requests. L’esempio seguente è pensato per Python 3.8 e versioni successive.
import csv
import os
import sys
from urllib.parse import urlencode
import requests
TIKTOK_KEY = os.environ.get("JSONSCRAPER_TIKTOK_LICENSE_KEY")
INSTAGRAM_KEY = os.environ.get("JSONSCRAPER_INSTAGRAM_LICENSE_KEY")
if not TIKTOK_KEY or not INSTAGRAM_KEY:
sys.exit("Set JSONSCRAPER_TIKTOK_LICENSE_KEY and JSONSCRAPER_INSTAGRAM_LICENSE_KEY")
def get_json(base_url, path, params):
response = requests.get(
f"{base_url}{path}",
params=params,
timeout=30,
)
response.raise_for_status()
return response.json()
def extract_videos(payload):
"""Handle both observed TikTok search result locations."""
if payload.get("status") != "ok":
raise RuntimeError(f"TikTok API status: {payload.get('status')}")
tiktok = payload.get("tiktok") or {}
videos = list(tiktok.get("aweme_list") or [])
for item in tiktok.get("search_item_list") or []:
video = item.get("aweme_info")
if video:
videos.append(video)
unique = {}
for video in videos:
video_id = video.get("aweme_id")
if video_id:
unique[video_id] = video
return list(unique.values())
keyword = "домашний кофе"
tiktok_payload = get_json(
"https://tiktok.evelode.com",
"/searchVideo",
{
"license_key": TIKTOK_KEY,
"keyword": keyword,
"count": 20,
"date_posted": "this-month",
"sort_by": "relevance",
},
)
rows = []
for video in extract_videos(tiktok_payload):
author = video.get("author") or {}
stats = video.get("statistics") or {}
rows.append({
"tiktok_video_id": video.get("aweme_id", ""),
"tiktok_url": video.get("share_url", ""),
"video_description": video.get("desc", ""),
"created_at": video.get("create_time", ""),
"tiktok_username": author.get("unique_id", ""),
"tiktok_author_name": author.get("nickname", ""),
"tiktok_followers": author.get("follower_count", ""),
"views": stats.get("play_count", ""),
"likes": stats.get("digg_count", ""),
"instagram_username": "",
"instagram_status": "not checked",
"instagram_followers": "",
"instagram_is_private": "",
"manual_match_review": "required",
})
# Compila questo dizionario solo con username trovati separatamente
# e aggiunti dopo aver verificato manualmente la fonte.
verified_instagram_usernames = {
# "tiktok_video_id": "instagram_username"
}
for row in rows:
username = verified_instagram_usernames.get(row["tiktok_video_id"])
if not username:
continue
ig_payload = get_json(
"https://ig.jsonscraper.com",
"/v1/user/by/username",
{
"license_key": INSTAGRAM_KEY,
"username": username,
},
)
if ig_payload.get("status") != "ok":
row["instagram_status"] = "api status: " + str(ig_payload.get("status"))
continue
profile = ig_payload.get("ig") or {}
row["instagram_username"] = profile.get("username", username)
row["instagram_status"] = "profile returned"
row["instagram_followers"] = profile.get("follower_count", "")
row["instagram_is_private"] = profile.get("is_private", "")
row["manual_match_review"] = "check relationship manually"
if rows:
with open("social_lead_checks.csv", "w", newline="", encoding="utf-8") as f:
writer = csv.DictWriter(f, fieldnames=rows[0].keys())
writer.writeheader()
writer.writerows(rows)
else:
print("No video rows returned for this query.")
Perché il gestore considera due strutture di risposta
Nei risultati di ricerca TikTok i video possono trovarsi in due posizioni: tiktok.aweme_list e tiktok.search_item_list[].aweme_info. Nella risposta di ricerca osservata, il primo elenco poteva essere vuoto mentre gli elementi si trovavano nel secondo. Per questo l’esempio unisce le due fonti ed elimina i duplicati in base a aweme_id. Controlla prima lo status esterno, quindi legge l’oggetto tiktok.
Il codice salva solo i campi effettivamente presenti nella risposta. Un valore vuoto indica che il campo mancava nell’oggetto ricevuto; non va interpretato come un valore pari a zero. È utile salvare link e descrizioni dei video insieme alle metriche: altrimenti, quando si consulta la tabella in seguito, si perde il contesto originale.
Aggiungi la paginazione solo se serve
L’esempio richiede una sola pagina ed elabora esclusivamente gli elementi restituiti. Se occorre proseguire la ricerca, la documentazione prevede il parametro cursor per la ricerca dei video; il valore si ricava dalla risposta precedente. Conserva il cursor come valore opaco e trasmettilo senza calcoli autonomi. Interrompi il ciclo quando la risposta indica che non ci sono altre pagine oppure quando viene raggiunto il limite stabilito dal team. La paginazione amplia l’insieme dei risultati restituiti, ma non consente di definirlo una copertura esaustiva di tutte le pubblicazioni sull’argomento.
Prima di aggiungere l’esportazione automatica, verifica una risposta reale con la tua chiave e scegli un numero moderato di pagine. Conserva il JSON originale insieme alla riga normalizzata, oppure in un file separato per data di esecuzione: così potrai capire se un campo della risposta è cambiato e rielaborare i dati raccolti se lo schema viene modificato.
Come usare il CSV per la qualificazione
Nella tabella puoi filtrare le righe in base alla presenza di un link al video, di una descrizione, di un autore e di un profilo IG compilato. Per la prima fase di verifica sono utili stati semplici: «video trovato», «username IG trovato», «profilo restituito», «collegamento tra account verificato da una persona» ed «escluso». Gli stati descrivono l’avanzamento della verifica, non la qualità o le intenzioni dell’autore.
Se serve un report ripetibile, esegui lo script secondo una pianificazione e aggiungi una colonna separata con la data di acquisizione dei dati. Il confronto tra le diverse istantanee mostrerà cosa è cambiato nei campi disponibili tra un’esecuzione e l’altra, per esempio nel numero di follower del profilo. I dati di TikTok e IG vanno conservati separatamente, indicando la piattaforma e il momento dell’osservazione: si tratta di contesti e risposte API diversi.
Per un flusso più ampio, sostituisci il CSV con un database che usi una chiave primaria composta dalla piattaforma e dall’ID del video. Conserva il testo della ricerca originale, l’ora di raccolta e la risposta non elaborata. È preferibile inviare una notifica su Slack o trasferire una riga al CRM solo dopo che una persona ha confermato il collegamento tra i profili, non appena viene rilevato un nome simile.
Limiti di interpretazione e uso sicuro
La ricerca per frase chiave restituisce i risultati trovati dall’API, non un elenco completo delle pubblicazioni. Il numero di visualizzazioni, like e follower è un’istantanea della risposta al momento della richiesta. Può servire per ordinare l’elenco di lavoro e svolgere verifiche successive, ma da solo non conferma un’intenzione commerciale, il tipo di pubblico o il consenso a essere contattati.
Conferma il collegamento tra i profili sulla base di segnali pubblici espliciti e annota chi ha svolto la verifica e quando. Se lo username IG proviene da una tabella di terze parti senza una fonte verificabile, lascia lo stato su «da verificare». Un profilo privato o dati mancanti devono essere indicati come esito distinto della verifica, senza tentare di colmare le lacune con supposizioni.
Usa le chiavi in un sistema di gestione dei segreti dell’ambiente di lavoro, limita l’accesso ai file esportati e definisci un periodo di conservazione coerente con lo scopo della ricerca. Trasferisci al CRM solo i campi necessari per il successivo lavoro manuale e rispetta le regole delle piattaforme applicabili e i requisiti per il trattamento dei dati.
Il risultato finale
Al termine dell’esecuzione avrai un CSV con l’elenco dei video trovati, i relativi autori e le metriche disponibili, oltre a campi separati per la verifica di IG. Puoi eseguire lo script manualmente, pianificarlo in CI oppure usare un nodo di richiesta HTTP in una piattaforma di automazione. Il principio pratico fondamentale è automatizzare la raccolta e la struttura dei dati, lasciando la verifica del collegamento tra account a una persona.
Per controllare gli endpoint e i parametri disponibili, parti da TikTok Scraper API e IG Scraper API. Le pagine dei prodotti offrono esempi di richieste e collegamenti alla documentazione; inizia con una richiesta ridotta prima di integrare la raccolta in un processo continuativo.
