IG: come individuare i problemi nei profili pubblici prima del lancio di una campagna

Prima del lancio di una campagna, è possibile elaborare con uno script un elenco di account IG e ottenere un report JSON con la risposta dell’API per ciascun nome. L’endpoint IG Scraper API di jsonscraper restituisce uno stato esterno e un oggetto profilo; lo schema osservato include nome utente, indicatori di privacy e verifica, numero di post, follower e account seguiti. Questi campi aiutano a selezionare le voci da controllare manualmente, ma da soli non spiegano perché una risposta sia assente o inattesa.

Il problema: l’elenco degli account sembra corretto, ma è pronto all’uso?

Nel foglio di lavoro di una campagna possono esserci account rinominati, refusi e profili privati. Se il team inizia ad analizzare l’elenco senza un controllo preliminare, qualcuno deve aprire gli account uno per uno. Un’elaborazione automatica riduce il lavoro manuale e conserva un registro uniforme di ciò che l’API ha restituito per ciascun nome richiesto.

L’obiettivo di questo flusso è circoscritto: scorrere l’elenco, salvare le risposte HTTP effettive e i dati JSON, quindi segnalare per una verifica manuale i profili con le caratteristiche rilevanti per la campagna. Il report registra i dati osservati; non stabilisce perché un profilo non sia stato restituito o perché la richiesta sia terminata con un errore.

Che cosa controlla la richiesta

La documentazione di jsonscraper indica l’endpoint GET \/v1\/user\/by\/username. Il parametro obbligatorio è username; la chiave si passa come license_key. Il parametro facoltativo cache_timeout attiva la memorizzazione nella cache per il numero di secondi indicato, mentre 0 la lascia disattivata. Lo schema osservato di una risposta riuscita contiene uno status esterno e un oggetto ig con i campi del profilo.

Per la diagnostica, distinguete tre fatti: se la richiesta HTTP è stata eseguita; se il JSON analizzato contiene un oggetto ig; quali campi sono presenti in quell’oggetto. Se una fase non si conclude come previsto, lo script può registrare l’esito tecnico e la risposta originale. Questo esito segnala la necessità di una verifica, ma non determina la causa del problema.

Preparate i dati di input e la chiave

Create il file usernames.txt, inserendo un nome utente per riga senza il simbolo @. Eliminate le righe vuote e i duplicati, mantenendo solo gli account pertinenti alla campagna. Per confrontare i risultati in seguito, conservate separatamente la data del controllo e l’identificativo del progetto.

Conservate la chiave nella variabile d’ambiente JSONSCRAPER_INSTAGRAM_LICENSE_KEY, non nel codice sorgente o nel repository:

export JSONSCRAPER_INSTAGRAM_LICENSE_KEY="la_tua_chiave"
python3 check_profiles.py

L’esempio usa la libreria standard di Python 3.8+ e non richiede l’installazione di pacchetti HTTP.

Esempio: richiedere i profili e salvare un report

Lo script scorre l’elenco un nome alla volta. In caso di risposta JSON riuscita, salva il corpo effettivo e i campi del profilo disponibili; in caso di errore HTTP o di rete, lo registra come esito tecnico. I campi assenti restano null e il corpo grezzo della risposta viene salvato, se è stato possibile leggerlo.

import json
import os
import time
from datetime import datetime, timezone
from urllib.error import HTTPError, URLError
from urllib.parse import urlencode
from urllib.request import Request, urlopen

API_KEY = os.environ.get("JSONSCRAPER_INSTAGRAM_LICENSE_KEY")
if not API_KEY:
    raise SystemExit("Imposta JSONSCRAPER_INSTAGRAM_LICENSE_KEY")

BASE_URL = "https:\/\/ig.jsonscraper.com\/v1\/user\/by\/username"

with open("usernames.txt", encoding="utf-8") as f:
    usernames = list(dict.fromkeys(
        line.strip().lstrip("@") for line in f if line.strip()
    ))

results = []
for username in usernames:
    params = urlencode({"username": username, "license_key": API_KEY})
    request = Request(f"{BASE_URL}?{params}", method="GET")
    checked_at = datetime.now(timezone.utc).isoformat()

    try:
        with urlopen(request, timeout=30) as response:
            http_status = response.status
            raw_body = response.read().decode("utf-8")
        try:
            payload = json.loads(raw_body)
            json_error = None
        except json.JSONDecodeError as exc:
            payload = None
            json_error = str(exc)

        profile = payload.get("ig") if isinstance(payload, dict) else None
        record = {
            "requested_username": username,
            "checked_at": checked_at,
            "http_status": http_status,
            "api_status": payload.get("status") if isinstance(payload, dict) else None,
            "check_result": "profile_returned" if isinstance(profile, dict) else "unexpected_or_missing_profile_object",
            "response": payload if payload is not None else raw_body,
        }
        if json_error:
            record["json_error"] = json_error
        if isinstance(profile, dict):
            record["returned_username"] = profile.get("username")
            record["is_private"] = profile.get("is_private")
            record["is_verified"] = profile.get("is_verified")
            record["media_count"] = profile.get("media_count")
            record["follower_count"] = profile.get("follower_count")
            record["following_count"] = profile.get("following_count")
        results.append(record)
    except HTTPError as exc:
        body = exc.read().decode("utf-8", errors="replace")
        results.append({
            "requested_username": username,
            "checked_at": checked_at,
            "check_result": "http_error",
            "http_status": exc.code,
            "response": body,
        })
    except (URLError, TimeoutError) as exc:
        results.append({
            "requested_username": username,
            "checked_at": checked_at,
            "check_result": "request_error",
            "detail": str(exc),
        })

    time.sleep(0.5)

with open("profile-check.json", "w", encoding="utf-8") as f:
    json.dump(results, f, ensure_ascii=False, indent=2)

print(f"Risultati salvati: {len(results)}")

Questo è un esempio di integrazione, non il resoconto di un test eseguito. La chiave viene passata nel parametro license_key, ma non viene stampata. La risposta completa può contenere informazioni il cui accesso dovrebbe essere limitato secondo le regole di conservazione dei dati del team.

Come leggere i risultati

Il record profile_returned significa che lo script ha ricevuto un oggetto JSON ig. Confrontate requested_username con returned_username e controllate gli indicatori rilevanti per il processo della campagna. Per esempio, se la campagna richiede un profilo pubblico, un valore is_private: true può essere segnalato per una verifica manuale.

I risultati http_error, request_error e unexpected_or_missing_profile_object indicano soltanto la fase in cui lo script non ha ottenuto la struttura prevista. Non dimostrano che l’account sia stato eliminato, sia privato o non sia accessibile per una ragione specifica. Salvate la risposta, controllate il nome e la chiave, quindi riprovate la richiesta oppure contattate il canale di assistenza ufficiale del servizio.

Se un campo è assente, lasciatelo sconosciuto: non interpretate l’assenza come zero o false. I contatori del profilo descrivono lo stato restituito al momento della richiesta. L’indicazione temporale permette di distinguere questa istantanea dai risultati di un’esecuzione successiva.

Automatizzare senza perdere osservabilità

Spostate l’esecuzione in un pianificatore di attività o in una fase del processo ETL esistente. Conservate la data del controllo, il nome richiesto, l’esito, lo stato e il corpo della risposta. In una fase separata potete caricare il JSON in una tabella e inviare a uno specialista soltanto i record da verificare.

Per rilevare le modifiche, confrontate le istantanee dello stesso profilo in base ai campi selezionati. Una variazione del numero di post è un motivo per aprire il profilo e controllarlo, non una data precisa di pubblicazione. Anche il numero di follower è un valore rilevato al momento della richiesta, quindi la cronologia delle osservazioni si costruisce a partire dalle istantanee salvate.

Per elenchi numerosi, impostate una frequenza controllata, aggiungete tentativi ripetuti con un limite e tenete un registro degli errori. Non inserite la chiave nei log degli URL. Conservare separatamente l’elenco di input e i risultati aiuta a capire quali account sono già stati elaborati.

Risultato atteso

Si ottiene un file JSON con l’esito dell’elaborazione di ogni nome richiesto, la data e l’ora, gli attributi disponibili e la risposta salvata. Prima di passare l’elenco alla campagna, è possibile filtrare le corrispondenze, i profili privati e i casi tecnici da verificare manualmente. I criteri per la fase successiva vengono stabiliti dal team.

L’endpoint e i parametri sono descritti nella documentazione dell’API IG; le informazioni sul prodotto sono disponibili nella pagina di IG Scraper API. Iniziate con un piccolo campione, verificate la forma effettiva delle risposte e adattate le regole del report al vostro processo.