Як аналізувати теми TikTok-креаторів: практичний пайплайн на Python

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

Практичний підхід — вести невеликий список публічних акаунтів, регулярно отримувати відомості про їхні відео у структурованому вигляді й зберігати кожне збирання як окремий знімок. Потім можна порівнювати публікації та доступні метрики в часі, а мовну модель використовувати для попереднього групування підписів. Нижче — схема такого дослідницького пайплайна на Python із TikTok Scraper API від jsonscraper.

Сформулюйте запитання до збирання даних

Уявімо маркетингову команду невеликого бренду спортивного харчування. Їй потрібно з’ясувати, які теми регулярно з’являються у вибраних публічних TikTok-креаторів і які відео варто переглянути вручну. Завдання — порівняти публікації заздалегідь вибраних акаунтів за період спостереження, а не побудувати універсальний рейтинг популярності TikTok.

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

До підключення API запишіть протокол дослідження: список акаунтів, дату початку, періодичність збирання, поля аналізу та критерії включення публікацій. Фіксуйте час кожного запиту. Тоді можна відрізнити зміну метрики одного відео від різниці між двома наборами спостережень.

Що збирати й що обчислювати

Для невеликого проєкту потрібні три рівні даних. Перший — ідентифікатор акаунта й час запуску збирання. Другий — вихідна відповідь API, збережена для подальшої перевірки. Третій — нормалізовані поля для запитів і звітів: ID відео, підпис, час публікації та доступні лічильники взаємодій.

Назви полів і вкладеність відповіді потрібно встановити за зразком конкретного маршруту. Не закладайте заздалегідь припущення, що список завжди називається videos або лічильник переглядів — views. Спочатку виконайте документований запит і вивчіть фактичний JSON, а потім налаштуйте перетворення у власну схему.

Корисні показники — кількість нових публікацій за інтервал, розподіл публікацій за темами та зміна публічних лічильників між знімками одного відео. Для останнього порівнюйте записи з однаковим ID відео. Так динаміка вже опублікованого ролика залишається відокремленою від показників нових публікацій.

Підключення TikTok Scraper API

В описі TikTok Scraper API зазначено базову адресу https://tiktok.evelode.com, а довідник маршрутів підтверджує GET /getUserFeed і параметри query, max_cursor, count, region, with_pinned_posts, sort_type і cache_timeout. Для першого запиту достатньо вказати профіль у query і, наприклад, кількість елементів через count. Ключ license_key передається в query string; його налаштування також описує довідник API. У колекції Postman можна звірити endpoint і перевірити відповідь перед інтеграцією.

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

Мінімальний робочий запит на Python

Довідник зазначає, що відповідь стрічки користувача містить зовнішній статус і об’єкт tiktok, де список публікацій розміщено в aweme_list. У записах можуть бути ID, підпис, час публікації, автор і статистика. Конкретні поля та значення слід перевіряти за отриманою відповіддю: деякі дані можуть бути відсутні.

import json
import os
from datetime import datetime, timezone
from pathlib import Path

import requests

API_KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
ENDPOINT_URL = "https://tiktok.evelode.com/getUserFeed"


def fetch_user_feed(handle: str, count: int = 20) -> dict:
    response = requests.get(
        ENDPOINT_URL,
        params={
            "license_key": API_KEY,
            "query": handle,
            "count": count,
            "region": "US",
        },
        timeout=45,
    )
    response.raise_for_status()
    payload = response.json()
    if not isinstance(payload, dict):
        raise ValueError("Очікувався об’єкт JSON")
    if payload.get("status") != "ok":
        raise RuntimeError(f"API повернув статус: {payload.get('status')!r}")
    tiktok = payload.get("tiktok")
    if not isinstance(tiktok, dict):
        raise ValueError("У відповіді відсутній об’єкт tiktok")
    return payload


def save_raw(payload: dict, account: str, output_dir: str = "data/raw") -> Path:
    collected_at = datetime.now(timezone.utc).isoformat()
    safe_account = "".join(c for c in account if c.isalnum() or c in "-_@")
    path = Path(output_dir) / f"{safe_account}_{collected_at.replace(':', '-')}.json"
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_text(
        json.dumps(
            {"collected_at": collected_at, "account": account, "payload": payload},
            ensure_ascii=False,
            indent=2,
        ),
        encoding="utf-8",
    )
    return path


def normalize_items(payload: dict, account: str, collected_at: str) -> list:
    items = payload["tiktok"].get("aweme_list", [])
    if not isinstance(items, list):
        raise ValueError("Поле tiktok.aweme_list не є списком")

    observations = []
    for item in items:
        if not isinstance(item, dict):
            continue
        stats = item.get("statistics")
        stats = stats if isinstance(stats, dict) else {}
        author = item.get("author")
        author = author if isinstance(author, dict) else {}
        observations.append({
            "account_handle": account,
            "collected_at": collected_at,
            "video_id": item.get("aweme_id"),
            "caption": item.get("desc"),
            "published_at_epoch": item.get("create_time"),
            "author_handle": author.get("unique_id"),
            "views": stats.get("play_count"),
            "likes": stats.get("digg_count"),
            "comments": stats.get("comment_count"),
            "shares": stats.get("share_count"),
        })
    return observations


if __name__ == "__main__":
    account = "creator_handle"
    payload = fetch_user_feed(account, count=20)
    collected_at = datetime.now(timezone.utc).isoformat()
    raw_path = save_raw(payload, account)
    observations = normalize_items(payload, account, collected_at)
    print(f"Збережено: {raw_path}; записів: {len(observations)}")

Перед запуском задайте JSONSCRAPER_TIKTOK_LICENSE_KEY в середовищі та встановіть бібліотеку requests. Код перевіряє HTTP-відповідь, зовнішній статус і наявність об’єкта tiktok, після чого читає aweme_list. Він зберігає сирий JSON і витягує підтверджені довідником поля, залишаючи відсутні значення порожніми. Отримана стрічка — це набір результатів, повернутий API, тому звіт слід пов’язувати з часом запиту й вибраним профілем.

Зберігайте знімки й порівнюйте публікації

Для невеликого проєкту підійдуть SQLite або PostgreSQL. Зберігайте сиру відповідь окремо від нормалізованих записів. Для таблиці спостережень можна використати таку схему:

CREATE TABLE IF NOT EXISTS video_observations (
    account_handle TEXT NOT NULL,
    video_id TEXT NOT NULL,
    collected_at TEXT NOT NULL,
    published_at_epoch INTEGER,
    caption TEXT,
    views INTEGER,
    likes INTEGER,
    comments INTEGER,
    shares INTEGER,
    raw_file TEXT,
    PRIMARY KEY (account_handle, video_id, collected_at)
);

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

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

Додайте мовну модель із перевірюваним маркуванням

Модель може попередньо розподіляти підписи за темами на кшталт «рецепти», «тренування», «огляди продуктів» і «особисті історії». Для початку вручну розмітьте кілька десятків публікацій. Порівняйте автоматичні мітки з цими прикладами, уточніть визначення категорій і повторіть оцінювання після зміни промпту або моделі.

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

Зберігайте разом із міткою ID публікації, версію промпту, дату обробки та використану модель. Якщо класифікацію виконано неправильно, аналітик зможе знайти підпис і виправити правило. Початкову мітку й ручне коригування варто зберігати окремо.

Автоматизуйте запуск

Після перевірки ручного запуску перенесіть скрипт у cron, GitHub Actions, n8n або Make. Планувальник запускає збирання за розкладом, передає список акаунтів, реєструє результат і надсилає звіт до вибраного сховища. Зберігайте ключ у секретах середовища виконання. Спочатку перевірте процес на одному акаунті, а потім розширюйте список.

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

Реєструйте час, акаунт, маршрут, HTTP-статус, тривалість, кількість оброблених елементів і опис помилки. Не записуйте API-ключ у журнал. Параметр cache_timeout зазначений для /getUserFeed; його можна додати до запиту, якщо потрібен визначений строк кешування. У довіднику API значення за замовчуванням описано як 3600 секунд.

Перевірте якість перед публікацією звіту

Зіставте кілька нормалізованих записів із вихідним JSON. Перевірте, що повторне збирання розпізнає те саме відео за ID, дати розбираються очікуваним чином, числові поля мають відповідний тип, а частка пропусків відома. Потім запустіть процес повторно й переконайтеся, що база зберегла старі спостереження та додала нові.

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

Зберігайте вихідний текст підпису й створюйте окремо очищену версію. Емодзі, хештеги, посилання й мовні особливості можуть впливати на класифікацію; окремі поля допоможуть перевірити вплив очищення та перерахувати категорії без нового звернення до API.

Який результат дасть пайплайн

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

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

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

Відповідальне збирання публічних даних

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

Перед передаванням даних до сервісу ШІ видаляйте поля, які моделі не потрібні. У звіті зазначайте ID публікації та дату спостереження, щоб співробітник міг перейти до запису й перевірити підставу висновку.

Короткий контрольний список запуску

1. Визначте нішу, список акаунтів, період і запитання для аналізу.
2. Перевірте параметри GET /getUserFeed у довіднику й фактичну відповідь у Postman.
3. Збережіть приклад JSON і налаштуйте нормалізатор для підтверджених полів.
4. Записуйте сиру відповідь і окремі знімки із часом збирання.
5. Обчислюйте числові показники кодом; використовуйте ШІ для попереднього групування тексту.
6. Додайте розклад, журналювання, обробку повторів і строк зберігання.

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