IG-Profile vor Kampagnenstart mit dem Briefing abgleichen: Prüfung per API

Vor dem Start einer Kampagne können Sie eine Liste von IG-Konten automatisch mit dem Briefing abgleichen und eine CSV-Datei erstellen, die nur Einträge enthält, die Aufmerksamkeit erfordern. Für jede Zeile fragt das Skript das Profil ab, vergleicht Benutzername, Sichtbarkeit und Verifizierung mit den erwarteten Werten und speichert außerdem verfügbare Kennzahlen. So wird aus einer wiederkehrenden manuellen Prüfung ein klarer Kontrollschritt, bevor die Kampagne in die Umsetzung geht.

Aufgabe: Abweichungen vor der Veröffentlichung erkennen

Eine Kampagnentabelle enthält üblicherweise den Namen des Kontos und einige Erwartungen: Das Profil soll öffentlich sein, der Benutzername muss dem vereinbarten entsprechen und der Verifizierungsstatus soll mit dem Eintrag im Briefing übereinstimmen. Zwischen der Erstellung der Liste und dem Start kann ein Konto seinen Namen ändern, privat werden oder sich als ein anderes Profil mit ähnlichem Namen herausstellen. Werden die Zeilen manuell geprüft, ist es schwierig, den Prozess zu wiederholen und Ausnahmen schnell herauszufiltern.

Für eine solche Vorabdiagnose genügt es, ein Profil anhand des Benutzernamens abzurufen. In der veröffentlichten jsonscraper-Dokumentation ist die Route GET /v1/user/by/username mit dem Parameter username angegeben; außerdem steht der optionale Parameter cache_timeout zur Verfügung. Die Antwort kann den Benutzernamen, den vollständigen Namen, die Merkmale private und verified, die Anzahl der Beiträge, Follower und gefolgten Konten sowie die Biografie enthalten. Lesen Sie die konkreten Felder aus der tatsächlichen Antwort aus: Ein Schema-Snapshot bestätigt zwar, dass sie in einer beobachteten Antwort vorhanden waren, doch Werte können abweichen oder fehlen.

Tabelle und Prüfregeln vorbereiten

Erstellen Sie eine CSV-Datei namens profiles.csv mit den Spalten username, expected_private und expected_verified. Tragen Sie in den beiden letztgenannten Spalten die erwarteten Werte true oder false ein und geben Sie den Benutzernamen ohne das Zeichen @ an. Ist die Erwartung für ein Profil unbekannt, lassen Sie das Feld leer: Das Skript soll aus einer fehlenden Erwartung keinen Fehler machen.

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

Die Prüfung erfüllt zwei eng umrissene Aufgaben: Sie stellt fest, ob der abgerufene Benutzername mit dem angefragten übereinstimmt, und erkennt Abweichungen von den festgehaltenen Erwartungen zu Sichtbarkeit und Verifizierung. Kennzahlen und Biografie werden als Kontext für die manuelle Bewertung gespeichert, nicht als Beleg für die Qualität der Zielgruppe oder die Eignung einer Person für eine Kampagne ausgelegt.

IG Scraper API einrichten

Speichern Sie den Zugriffsschlüssel in der Umgebungsvariable JSONSCRAPER_INSTAGRAM_LICENSE_KEY. Schreiben Sie das Geheimnis weder in die CSV-Datei noch in den Quellcode oder in Ausführungsprotokolle. Die offizielle Dokumentation zum IG-Endpunkt beschreibt die Route und Parameternamen; die API-Basisadresse lautet https://ig.jsonscraper.com und der Parametername für den Schlüssel ist license_key.

Führen Sie vor der Verarbeitung der vollständigen Liste einen Testaufruf für eine Testzeile aus, prüfen Sie die JSON-Struktur und vergewissern Sie sich, dass Ihr Konto Zugriff hat. Da der Endpunkt einen Benutzernamen entgegennimmt, sind für dieses einfache Szenario weder eine bekannte Profil-ID noch zusätzliche Routen erforderlich.

Beispiel: Anfragen, Abgleich und CSV-Datei mit Ausnahmen

Das folgende Skript ist mit Python 3.8 oder höher kompatibel. Es liest eine CSV-Datei ein, führt für jedes Profil eine GET-Anfrage aus, prüft den HTTP-Status der Antwort und speichert die relevanten Quelldaten zusammen mit dem Abgleichergebnis. Installieren Sie die Abhängigkeit mit python -m pip install requests und exportieren Sie vor dem Start den Schlüssel.

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)

Der Code prüft genau die beobachtete Antwortstruktur: den äußeren Wert status und das Profilobjekt ig. Ändert der Anbieter das Format, bricht die Strukturprüfung die Verarbeitung des jeweiligen Eintrags ab und speichert einen Fehler, anstatt stillschweigend eine falsche Übereinstimmung zu erzeugen. Das Skript gibt den Schlüssel nicht aus und nimmt ihn nicht in die Ergebnisdatei auf.

Ergebnisse interpretieren

In preflight_results.csv haben Zeilen mit dem Status matched die festgelegten Abgleiche bestanden. Der Wert review bedeutet, dass ein oder mehrere Merkmale vom Briefing abweichen; die Spalte checks zeigt genau welche. Ein Anfrage- oder Antwortfehler wird separat ausgewiesen, sodass nicht verfügbare Daten nicht wie eine bestätigte Übereinstimmung erscheinen.

Die Anzahl der Follower und Beiträge hilft dabei, den aktuellen Profilstand neben der Bewerbung zu sehen. Es handelt sich um Momentaufnahmen aus der Antwort auf die Anfrage. Um Veränderungen im Zeitverlauf zu bewerten, speichern Sie separate, datierte Läufe; eine einzelne Prüfung enthält keinen Verlauf. Felder können leer sein. In diesem Fall bleibt der Eintrag für die Prüfung der Identität und anderer verfügbarer Merkmale nutzbar, nicht aber für den Vergleich einer fehlenden Kennzahl.

Vor dem Kampagnenstart automatisieren

Fügen Sie das Skript nach der manuellen Prüfung einer Test-CSV einem Zeitplan oder einem Vorbereitungsschritt für die Kampagne hinzu. Für eine reproduzierbare Kontrolle sollten Sie die ursprüngliche Liste separat aufbewahren, das Ausführungsdatum festhalten und die Ergebnis-CSV in einem zugriffsbeschränkten Arbeitsbereich speichern. Wenn sich Benutzernamen ändern können, verwenden Sie für die erneute Verarbeitung möglichst eine stabile Zeilen-ID aus Ihrem System.

Ergänzen Sie bei einer längeren Liste eine Begrenzung der Parallelität, Wiederholungsversuche ausschließlich für vorübergehende Netzwerkfehler und ein separates Fehlerprotokoll ohne Geheimnisse. Starten Sie keine endlosen Wiederholungen für einen ungültigen Schlüssel oder einen fehlerhaften Benutzernamen. Den Wert cache_timeout sollten Sie nur entsprechend der gewünschten Aktualitätsrichtlinie hinzufügen: Laut Dokumentation ist das Caching für IG standardmäßig deaktiviert; ein Wert größer als null aktiviert es für den festgelegten Zeitraum.

Die Profilprüfung reduziert den manuellen Abgleich auf eine konkrete Ausnahmenliste: Benutzername, Sichtbarkeit, Verifizierung und verfügbare Kennzahlen stehen vor dem Kampagnenstart in einer Tabelle. Informationen zu API-Parametern und aktuellen Integrationsmöglichkeiten finden Sie auf der Seite zur IG Scraper API und in der Dokumentation der Routen.