Vérifiez les profils IG par rapport au brief de campagne avant le lancement : contrôle via API

Avant le lancement d’une campagne, vous pouvez comparer automatiquement une liste de comptes IG au brief et obtenir un CSV contenant uniquement les entrées qui nécessitent une attention particulière. Pour chaque ligne, le script interroge le profil, compare le nom d’utilisateur, le statut de confidentialité et la vérification aux valeurs attendues, et enregistre également les compteurs disponibles. Cette méthode transforme une vérification manuelle répétitive en une étape de contrôle claire avant la mise en œuvre de la campagne.

Objectif : repérer les écarts avant la publication

Le tableau d’une campagne indique généralement le nom du compte et quelques attentes : le profil doit être public, le nom d’utilisateur doit correspondre à celui qui a été approuvé et le statut de vérification doit correspondre à l’entrée du brief. Entre la préparation de la liste et le lancement, un compte peut changer de nom, devenir privé ou s’avérer être un autre profil au nom similaire. Lorsque les lignes sont vérifiées manuellement, il est difficile de reproduire le processus et de repérer rapidement les exceptions.

Pour ce diagnostic préalable, il suffit de récupérer le profil à partir de son nom d’utilisateur. La documentation publiée de jsonscraper indique la route GET /v1/user/by/username avec le paramètre username ; le paramètre facultatif cache_timeout est également disponible. La réponse peut contenir le nom d’utilisateur, le nom complet, les indicateurs private et verified, le nombre de publications, d’abonnés et d’abonnements, ainsi que la biographie. Les champs précis doivent être lus dans la réponse réelle : un instantané du schéma confirme leur présence dans la réponse observée, mais leurs valeurs peuvent varier ou être absentes.

Préparez le tableau et les règles de vérification

Créez un fichier CSV nommé profiles.csv avec les colonnes username, expected_private et expected_verified. Dans ces deux dernières colonnes, indiquez les valeurs attendues true ou false, et saisissez le nom d’utilisateur sans le caractère @. Si l’attente concernant un profil est inconnue, laissez la cellule vide : le script ne doit pas transformer l’absence d’attente en erreur.

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

Cette vérification répond à deux questions précises : le nom d’utilisateur récupéré correspond-il à celui qui a été demandé, et les propriétés de confidentialité et de vérification correspondent-elles aux attentes consignées ? Les compteurs et la biographie sont enregistrés à titre de contexte et pour une évaluation manuelle ; ils ne sont pas considérés comme une preuve de la qualité de l’audience ou de la pertinence d’un créateur pour une campagne.

Connectez-vous à l’IG Scraper API

Enregistrez votre clé d’accès dans la variable d’environnement JSONSCRAPER_INSTAGRAM_LICENSE_KEY. Ne placez pas ce secret dans le CSV, le code source ou les journaux d’exécution. La documentation officielle de l’endpoint IG décrit la route et les noms des paramètres ; l’adresse de base de l’API est https://ig.jsonscraper.com, et le nom du paramètre de clé est license_key.

Avant de traiter la liste complète, effectuez un appel de test pour une ligne fictive, vérifiez la structure JSON et assurez-vous que votre compte dispose d’un accès. Comme l’endpoint accepte un nom d’utilisateur, aucun identifiant de profil connu ni aucune route supplémentaire ne sont nécessaires pour ce scénario simple.

Exemple : requêtes, comparaison et CSV des exceptions

Le script suivant est compatible avec Python 3.8 et les versions ultérieures. Il lit le CSV, effectue une requête GET par profil, vérifie le statut HTTP de la réponse et enregistre les champs pertinents d’origine avec le résultat de la comparaison. Installez la dépendance à l’aide de la commande python -m pip install requests, puis exportez la clé avant l’exécution.

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)

Le code vérifie précisément l’enveloppe de réponse observée : le status externe et l’objet de profil ig. Si le fournisseur modifie le format, la vérification de structure interrompra le traitement de l’enregistrement concerné et enregistrera une erreur, au lieu de créer silencieusement une fausse correspondance. Le script n’affiche pas la clé et ne l’inclut pas dans le fichier de sortie.

Comment lire les résultats

Dans preflight_results.csv, les lignes portant le statut matched ont satisfait aux comparaisons définies. La valeur review signifie qu’un ou plusieurs paramètres diffèrent du brief ; la colonne checks indique lesquels. Les erreurs de requête ou de réponse sont signalées séparément, afin qu’une indisponibilité des données ne soit pas interprétée comme une correspondance confirmée.

Le nombre d’abonnés et de publications permet à une personne de voir un instantané actuel du profil à côté de la demande. Il s’agit de valeurs ponctuelles provenant de la réponse à la requête. Pour évaluer les changements au fil du temps, enregistrez des exécutions datées séparément ; une vérification unique ne contient pas d’historique. Certains champs peuvent être vides : l’enregistrement reste alors exploitable pour vérifier l’identité et les autres attributs disponibles, mais pas pour comparer un compteur manquant.

Automatiser le contrôle avant le lancement de la campagne

Après la vérification manuelle d’un CSV de test, ajoutez le script à une tâche planifiée ou à une étape de préparation de campagne. Pour assurer la reproductibilité du contrôle, conservez séparément la liste d’origine, consignez la date d’exécution et enregistrez le CSV des résultats dans un espace de travail protégé. Si le nom d’utilisateur peut changer, il est utile d’utiliser un identifiant de ligne stable provenant de votre système pour relancer le traitement.

Lorsque la liste s’allonge, ajoutez une limite au parallélisme, des tentatives supplémentaires uniquement pour les erreurs réseau temporaires et un journal distinct des codes d’erreur, sans secrets. Ne relancez pas indéfiniment les requêtes avec une clé invalide ou un nom d’utilisateur incorrect. N’ajoutez cache_timeout qu’en fonction de la fraîcheur des données souhaitée : la documentation précise que la mise en cache IG est désactivée par défaut et qu’une valeur supérieure à zéro active le cache pour la durée indiquée.

Le contrôle du profil réduit les vérifications manuelles à une liste précise d’exceptions : nom, visibilité publique, vérification et compteurs disponibles figurent dans un même tableau avant le lancement de la campagne. Pour les paramètres de l’API et les options d’intégration à jour, consultez la page de l’IG Scraper API et la documentation des routes.