Як виявити TikTok-відео зі зростанням залученості, не порівнюючи сирі перегляди

Щоб зрозуміти, чи набирає конкретне TikTok-відео реакції, порівнюйте його публічні метрики з власним попереднім знімком. Одноразовий пошук показує вже накопичені перегляди та реакції; повторний збір тих самих знайдених роликів дає змогу побачити зміни між двома запусками. Нижче — мінімальний робочий пайплайн на Python: запит до пошуку, збереження метрик у CSV і розрахунок різниці.

Що саме вимірює такий моніторинг?

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

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

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

Як організовано збір через API?

У документації TikTok Scraper API описано GET-маршрут /searchVideo. Для пошуку обов’язковий рядок keyword; серед додаткових параметрів — count, region, sort_by і date_posted. Ключ API передається як license_key. У довіднику вказано базову адресу https://tiktok.evelode.com.

Відповідь містить зовнішній статус і об’єкт tiktok. У результатах пошуку відео можуть міститися в tiktok.aweme_list або всередині tiktok.search_item_list[].aweme_info. Наведений нижче обробник підтримує обидва формати. Метрики беруться з statistics, зокрема play_count, digg_count, comment_count і share_count; відсутнє значення зберігається порожнім, а не замінюється нулем.

Довідник маршрутів містить cursor для перегляду наступних результатів пошуку й указує допустимі варіанти для date_posted і sort_by. Для простого повторюваного моніторингу спочатку достатньо отримати одну сторінку результатів і зафіксувати відповідь, а пагінацію додавати лише за потреби. Якщо вона потрібна, передавайте отриманий курсор без змін.

Робочий приклад на Python

Установіть бібліотеку для HTTP-запитів командою python -m pip install requests і задайте ключ у змінній середовища JSONSCRAPER_TIKTOK_LICENSE_KEY. Скрипт приймає пошукову фразу як аргумент і додає знайдені знімки до одного CSV-файлу. Код сумісний із Python 3.8+.

import csv
import os
import sys
from datetime import datetime, timezone
from pathlib import Path

import requests

BASE_URL = "https://tiktok.evelode.com/searchVideo"
CSV_PATH = Path("tiktok_video_snapshots.csv")
FIELDS = [
    "collected_at", "aweme_id", "author", "description", "share_url",
    "play_count", "digg_count", "comment_count", "share_count",
]


def extract_items(payload):
    """Support the observed search response layouts."""
    data = payload.get("tiktok") or {}
    items = data.get("aweme_list") or []
    if items:
        return items

    found = []
    for result in data.get("search_item_list") or []:
        info = result.get("aweme_info")
        if info:
            found.append(info)
    return found


def main():
    key = os.environ.get("JSONSCRAPER_TIKTOK_LICENSE_KEY")
    if not key:
        raise SystemExit("Set JSONSCRAPER_TIKTOK_LICENSE_KEY first")
    if len(sys.argv) < 2:
        raise SystemExit('Usage: python collect.py "search phrase"')

    params = {
        "license_key": key,
        "keyword": sys.argv[1],
        "count": 20,
        "region": "US",
        "sort_by": "relevance",
        "date_posted": "this-week",
    }
    response = requests.get(BASE_URL, params=params, timeout=30)
    response.raise_for_status()
    payload = response.json()

    if payload.get("status") != "ok":
        raise RuntimeError("API returned a non-ok outer status")
    data = payload.get("tiktok") or {}
    items = extract_items(payload)
    collected_at = datetime.now(timezone.utc).isoformat()

    rows = []
    for item in items:
        stats = item.get("statistics") or {}
        author = item.get("author") or {}
        rows.append({
            "collected_at": collected_at,
            "aweme_id": item.get("aweme_id"),
            "author": author.get("unique_id") or author.get("nickname"),
            "description": item.get("desc"),
            "share_url": item.get("share_url"),
            "play_count": stats.get("play_count"),
            "digg_count": stats.get("digg_count"),
            "comment_count": stats.get("comment_count"),
            "share_count": stats.get("share_count"),
        })

    write_header = not CSV_PATH.exists()
    with CSV_PATH.open("a", newline="", encoding="utf-8") as file:
        writer = csv.DictWriter(file, fieldnames=FIELDS)
        if write_header:
            writer.writeheader()
        writer.writerows(rows)

    print("Saved", len(rows), "returned videos")
    print("has_more:", data.get("has_more"), "cursor:", data.get("cursor"))


if __name__ == "__main__":
    main()

Запустіть, наприклад, python collect.py "запит про продукт". Рядок із ключем передається бібліотекою в параметрах URL; скрипт не виводить його в термінал. Не зберігайте повний URL запиту у загальнодоступних журналах, адже він містить ключ. Для робочої системи використовуйте сховище секретів і обмежте доступ до файлу зі знімками.

Як обчислити приріст між запусками?

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

import csv
from collections import defaultdict
from pathlib import Path

rows_by_video = defaultdict(list)
with Path("tiktok_video_snapshots.csv").open(encoding="utf-8", newline="") as file:
    for row in csv.DictReader(file):
        if row["aweme_id"]:
            rows_by_video[row["aweme_id"]].append(row)

metrics = ("play_count", "digg_count", "comment_count", "share_count")
for video_id, snapshots in rows_by_video.items():
    snapshots.sort(key=lambda row: row["collected_at"])
    if len(snapshots) < 2:
        continue
    previous, latest = snapshots[-2], snapshots[-1]
    changes = {}
    for metric in metrics:
        old, new = previous[metric], latest[metric]
        changes[metric] = int(new) - int(old) if old and new else None
    print(video_id, changes, latest["share_url"])

Різниця дорівнює різниці двох збережених значень, а не швидкості зростання за гарантований проміжок часу. Якщо запуски відбуваються з різними інтервалами, додайте обчислення тривалості між collected_at і порівнюйте приріст за фактичний проміжок. Лічильники можуть змінюватися між спостереженнями; збережені позначки часу показують, коли саме отримано використані значення.

Як автоматизувати звіт і тлумачити його?

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

У таблиці зручно показувати ID і URL ролика, автора, опис, час збору та різниці за окремими метриками. Сортування за приростом переглядів відповідає на запитання про поширення, а приріст коментарів чи поширень допомагає виділити інший тип реакції. Не зводьте ці показники до єдиного рейтингу без чіткого правила: кожен лічильник має своє значення.

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

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

Що перевірити перед запуском за розкладом?

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

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