Verifica il profilo IG rispetto al brief della campagna prima del lancio: controllo tramite API

Prima del lancio di una campagna, puoi confrontare automaticamente un elenco di account IG con il brief e ottenere un CSV contenente solo le voci che richiedono attenzione. Per ogni riga, lo script richiede i dati del profilo, confronta username, stato di privacy e verifica con i valori attesi e salva anche i contatori disponibili. In questo modo, un controllo manuale ripetitivo diventa una verifica chiara da eseguire prima di avviare la campagna.

Obiettivo: individuare le discrepanze prima della pubblicazione

Un foglio di lavoro per una campagna include di solito il nome dell’account e alcune aspettative: il profilo deve essere pubblico, lo username deve corrispondere a quello concordato e il badge di verifica deve coincidere con quanto riportato nel brief. Tra la preparazione dell’elenco e il lancio, un account potrebbe cambiare nome, diventare privato oppure rivelarsi un altro profilo con un nome simile. Se controlli le righe manualmente, è difficile ripetere il processo e individuare rapidamente le eccezioni.

Per questo controllo preliminare basta recuperare il profilo tramite username. La documentazione pubblicata di jsonscraper indica la route GET /v1/user/by/username con il parametro username; è disponibile anche il parametro facoltativo cache_timeout. La risposta può includere username, nome completo, indicatori di privacy e verifica, numero di post, follower e account seguiti, oltre alla biografia. Leggi i campi presenti nella risposta effettiva: uno schema rilevato conferma che erano presenti nella risposta osservata, ma i valori possono variare o mancare.

Prepara il foglio di lavoro e le regole di verifica

Crea un CSV denominato profiles.csv con le colonne username, expected_private e expected_verified. Inserisci nelle ultime due colonne i valori attesi true o false e scrivi lo username senza il simbolo @. Se non conosci il valore atteso per un profilo, lascia vuota la cella: lo script non deve trattare l’assenza di un’aspettativa come un errore.

username,expected_private,expected_verified
examplebrand,false,true
anotheraccount,false,false

Il controllo svolge due compiti specifici: determina se lo username restituito corrisponde a quello richiesto e rileva eventuali differenze rispetto alle aspettative registrate per privacy e verifica. I contatori e la biografia vengono salvati come contesto per una valutazione manuale, ma non sono interpretati come prova della qualità del pubblico o dell’idoneità del creator alla campagna.

Collega IG Scraper API

Salva la chiave di accesso nella variabile d’ambiente JSONSCRAPER_INSTAGRAM_LICENSE_KEY. Non inserire il segreto nel CSV, nel codice sorgente o nei log di esecuzione. La documentazione ufficiale dell’endpoint IG descrive la route e i nomi dei parametri; l’indirizzo base dell’API è https://ig.jsonscraper.com e il nome del parametro per la chiave è license_key.

Prima di elaborare l’intero elenco, effettua una chiamata di prova per una riga di test, controlla la struttura JSON e verifica che il tuo account abbia accesso. Poiché l’endpoint accetta uno username, per questo semplice scenario non servono un identificatore di profilo noto né route aggiuntive.

Esempio: richieste, confronti e CSV delle eccezioni

Lo script seguente è compatibile con Python 3.8 e versioni successive. Legge il CSV, esegue una richiesta GET per ciascun profilo, controlla lo stato HTTP della risposta e salva i campi originali rilevanti insieme all’esito del confronto. Installa la dipendenza con python -m pip install requests, quindi imposta la chiave prima dell’esecuzione.

import csv
import os
import time
from pathlib import Path

import requests

BASE_URL = "https://ig.jsonscraper.com/v1/user/by/username"
API_KEY = os.environ["JSONSCRAPER_INSTAGRAM_LICENSE_KEY"]
INPUT_FILE = Path("profiles.csv")
OUTPUT_FILE = Path("preflight_results.csv")


def parse_expected(value):
    value = (value or "").strip().lower()
    if value == "true":
        return True
    if value == "false":
        return False
    return None


def profile_from_response(payload):
    # The documented observed response wraps profile fields in "ig".
    if payload.get("status") != "ok":
        raise ValueError("API response status is not ok")
    profile = payload.get("ig")
    if not isinstance(profile, dict):
        raise ValueError("Response has no profile object under 'ig'")
    return profile


with INPUT_FILE.open(newline="", encoding="utf-8") as source:
    rows = list(csv.DictReader(source))

results = []
for row in rows:
    requested = (row.get("username") or "").strip().lstrip("@")
    if not requested:
        results.append({
            "requested_username": "",
            "result": "missing_username",
            "error": "username is empty",
        })
        continue

    try:
        response = requests.get(
            BASE_URL,
            params={"username": requested, "license_key": API_KEY},
            timeout=30,
        )
        response.raise_for_status()
        profile = profile_from_response(response.json())

        actual_username = profile.get("username")
        actual_private = profile.get("is_private")
        actual_verified = profile.get("is_verified")
        expected_private = parse_expected(row.get("expected_private"))
        expected_verified = parse_expected(row.get("expected_verified"))

        checks = []
        if actual_username and actual_username.casefold() != requested.casefold():
            checks.append("username_mismatch")
        if expected_private is not None and actual_private != expected_private:
            checks.append("privacy_mismatch")
        if expected_verified is not None and actual_verified != expected_verified:
            checks.append("verification_mismatch")

        results.append({
            "requested_username": requested,
            "username": actual_username,
            "full_name": profile.get("full_name"),
            "is_private": actual_private,
            "is_verified": actual_verified,
            "media_count": profile.get("media_count"),
            "follower_count": profile.get("follower_count"),
            "following_count": profile.get("following_count"),
            "result": "review" if checks else "matched",
            "checks": ";".join(checks),
            "error": "",
        })
    except (requests.RequestException, ValueError, KeyError) as exc:
        results.append({
            "requested_username": requested,
            "result": "request_or_response_error",
            "error": str(exc),
        })

    # A small delay spaces requests; it is not a documented quota guarantee.
    time.sleep(0.5)

fieldnames = sorted({key for item in results for key in item})
with OUTPUT_FILE.open("w", newline="", encoding="utf-8") as destination:
    writer = csv.DictWriter(destination, fieldnames=fieldnames)
    writer.writeheader()
    writer.writerows(results)

print("Saved", len(results), "rows to", OUTPUT_FILE)

Il codice controlla la struttura della risposta osservata: lo status esterno e l’oggetto profilo ig. Se il fornitore modifica il formato, il controllo della struttura interrompe l’elaborazione della singola riga e registra un errore, invece di creare silenziosamente una corrispondenza errata. Lo script non stampa la chiave e non la inserisce nel file finale.

Come leggere il risultato

Nel file preflight_results.csv, le righe con stato matched hanno superato i confronti configurati. Il valore review indica che uno o più parametri differiscono dal brief; la colonna checks specifica quali. Gli errori di richiesta o di risposta sono segnalati separatamente, così l’indisponibilità dei dati non viene scambiata per una corrispondenza confermata.

Il numero di follower e di post aiuta a confrontare l’istantanea attuale del profilo con la candidatura. Sono valori rilevati al momento della risposta alla richiesta. Per valutare i cambiamenti nel tempo, conserva esecuzioni separate con le relative date: un singolo controllo non contiene dati storici. Alcuni campi possono essere vuoti; in tal caso la riga resta utile per verificare l’identità e gli altri attributi disponibili, ma non per confrontare un contatore assente.

Automatizza il controllo prima del lancio della campagna

Dopo aver verificato manualmente un CSV di prova, aggiungi lo script a una pianificazione o a una fase di preparazione della campagna. Per rendere il controllo ripetibile, conserva separatamente l’elenco originale, registra la data di esecuzione e salva il CSV dei risultati in un archivio di lavoro ad accesso riservato. Se lo username può cambiare, per elaborare nuovamente le righe è utile usare un identificatore stabile del tuo sistema.

Quando l’elenco cresce, aggiungi un limite alla concorrenza, tentativi aggiuntivi solo per gli errori di rete temporanei e un log separato dei codici di errore, senza segreti. Non ripetere all’infinito le richieste con una chiave non valida o uno username non corretto. Aggiungi il valore cache_timeout solo in base alla politica di aggiornamento necessaria: la documentazione indica che la cache per IG è disattivata per impostazione predefinita e che un valore maggiore di zero la attiva per il periodo specificato.

Il controllo del profilo riduce la verifica manuale a un elenco preciso di eccezioni: nome, privacy, verifica e contatori disponibili sono raccolti in un unico foglio prima dell’avvio della campagna. Per i parametri API e le opzioni d’integrazione aggiornate, consulta la pagina di IG Scraper API e la documentazione delle route.