Звірте профіль IG із брифом кампанії до запуску: перевірка через API

Перед запуском кампанії можна автоматично звірити список облікових записів IG із брифом і отримати CSV лише із записами, що потребують уваги. Для кожного рядка скрипт запитає профіль, порівняє username, статус приватності та верифікацію з очікуваними значеннями, а також збереже доступні лічильники. Це перетворює повторювану ручну перевірку на зрозумілий контрольний етап перед запуском кампанії.

Завдання: знайти розбіжності до публікації

У таблиці кампанії зазвичай є ім’я облікового запису та кілька очікувань: профіль має бути публічним, username має відповідати узгодженому, а позначка верифікації — збігатися із записом у брифі. Між підготовкою списку та запуском обліковий запис може змінити ім’я, стати приватним або виявитися іншим профілем зі схожою назвою. Якщо перевіряти рядки вручну, процес складно відтворити, а винятки — швидко виокремити.

Для такої попередньої діагностики достатньо отримати профіль за username. В опублікованій документації jsonscraper зазначено маршрут GET /v1/user/by/username із параметром username; також доступний необов’язковий параметр cache_timeout. У відповіді можуть бути username, повне ім’я, ознаки private і verified, кількість публікацій, підписників і підписок, а також біографія. Конкретні поля слід перевіряти у фактичній відповіді: знімок схеми підтверджує їх наявність у відповіді, зафіксованій під час спостереження, але значення можуть відрізнятися або бути відсутніми.

Підготуйте таблицю та правила перевірки

Створіть CSV-файл profiles.csv зі стовпцями username, expected_private і expected_verified. У двох останніх стовпцях укажіть очікувані значення true або false, а username запишіть без символу @. Якщо очікуване значення для якогось профілю невідоме, залиште клітинку порожньою: скрипт не має перетворювати відсутність очікування на помилку.

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

Тут перевірка виконує два вузькі завдання: визначає, чи збігається отримане ім’я користувача із запитаним, і виявляє відмінності від зафіксованих очікувань щодо приватності та верифікації. Лічильники й біографія зберігаються для контексту та ручної оцінки, а не трактуються як доказ якості аудиторії або придатності автора для кампанії.

Підключіть IG Scraper API

Збережіть ключ доступу в змінній середовища JSONSCRAPER_INSTAGRAM_LICENSE_KEY. Не записуйте секрет у CSV, вихідний код або журнали запуску. В офіційній документації endpoint IG описано маршрут і назви параметрів; базова адреса API — https://ig.jsonscraper.com, а назва параметра для ключа — license_key.

Перш ніж обробляти повний список, виконайте один пробний запит для тестового рядка, перевірте структуру JSON і переконайтеся, що ваш обліковий запис має доступ. Оскільки endpoint приймає username, відомий ідентифікатор профілю та додаткові маршрути для цього простого сценарію не потрібні.

Приклад: запити, порівняння та CSV із винятками

Наведений скрипт сумісний із Python 3.8+. Він читає CSV, виконує по одному GET-запиту для кожного профілю, перевіряє зовнішній статус відповіді та зберігає вихідні важливі поля разом із результатом порівняння. Установіть залежність командою python -m pip install requests, а потім експортуйте ключ перед запуском.

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)

У коді перевіряється саме спостережена обгортка відповіді: зовнішній status і об’єкт профілю ig. Якщо постачальник змінить формат, перевірка структури зупинить обробку конкретного запису й збереже помилку, а не мовчки створить хибний збіг. Скрипт не виводить ключ і не додає його до підсумкового файлу.

Як читати результат

У preflight_results.csv рядки зі статусом matched пройшли задані порівняння. Значення review означає, що один або кілька параметрів відрізняються від брифу; стовпець checks показує, які саме. Помилка запиту або відповіді позначається окремо, тому недоступність даних не виглядає як підтверджений збіг.

Кількість підписників і публікацій допомагає побачити поточний знімок профілю поруч із заявкою. Це миттєві значення з відповіді на запит. Щоб оцінювати зміни в часі, зберігайте окремі запуски з датами: одна перевірка не містить історії. Поля можуть бути порожніми; у такому разі запис придатний для перевірки ідентичності та інших доступних ознак, але не для порівняння відсутнього лічильника.

Автоматизація перед запуском кампанії

Після ручної перевірки тестового CSV додайте скрипт до розкладу або етапу підготовки кампанії. Для відтворюваного контролю зберігайте вихідний список окремо, записуйте дату запуску та зберігайте CSV із результатами в закритому робочому сховищі. Для повторної обробки зручно використовувати стабільний ідентифікатор рядка з вашої системи, якщо username може змінюватися.

Коли список зросте, додайте обмеження паралельності, повторні спроби лише для тимчасових мережевих помилок і окремий журнал кодів помилок без секретів. Не запускайте нескінченні повторні спроби через недійсний ключ або некоректний username. Значення cache_timeout додавайте лише відповідно до потрібної політики актуальності даних: у документації зазначено, що для IG кешування вимкнене за замовчуванням, а значення понад нуль вмикає кешування на заданий період.

Перевірка профілю зводить ручне звіряння до конкретного списку винятків: ім’я, публічність, верифікація та доступні лічильники опиняються в одній таблиці до початку кампанії. Щоб дізнатися про параметри API й актуальні варіанти інтеграції, скористайтеся сторінкою IG Scraper API та документацією маршрутів.