Как обнаружить 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

Установите библиотеку запросов командой 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 и сравнивать сохранённые метрики во времени. Такой подход отвечает на узкий практический вопрос — какие из уже найденных видео изменили публичные счётчики между двумя проверками — и оставляет исходные данные доступными для аудита и дальнейшей обработки.