TikTok: как проверить, что поисковый мониторинг действительно работает

HTTP 200 не гарантирует, что ежедневный мониторинг TikTok собрал видео. Результаты поиска могут находиться в aweme_list или в search_item_list[].aweme_info; скрипт, который читает только первый массив, способен завершиться без ошибки и записать пустой отчёт. Надёжная проверка отдельно подтверждает транспортный и прикладной статус, извлекает оба поддерживаемых варианта структуры и фиксирует, сколько уникальных видео удалось извлечь в этом запуске.

Что именно стоит диагностировать

Представьте задачу: команда каждое утро собирает публичные ролики по нескольким запросам, чтобы замечать новые публикации о продукте. Важный результат такого процесса — воспроизводимый список найденных записей с описанием, автором, датой публикации и доступными показателями. Если отчёт внезапно пуст, причина может быть в обработке JSON, изменившемся наборе результатов, повторной выдаче уже известных роликов или настоящем сбое запроса. Одно число — например, длина aweme_list — не помогает отличить эти случаи.

У jsonscraper TikTok Scraper API маршрут поиска /searchVideo принимает обязательный параметр keyword и дополнительные параметры count, cursor, date_posted, sort_by и region. Документация маршрута описывает пагинацию через cursor; его следует передавать как непрозрачное значение из предыдущего ответа. Параметр count задаёт желаемое число результатов, а не гарантию полного охвата публикаций.

Разделите проверку на четыре сигнала

Полезная диагностика складывается из четырёх независимых проверок. Первая — HTTP-запрос завершился успешно. Вторая — внешний status ответа равен ok, а внутренний tiktok.status_code соответствует успешному ответу. Третья — присутствует объект tiktok и записи извлекаются из обоих документированных мест ответа. Четвёртая — после дедупликации остались записи с идентификаторами, пригодными для хранения. В журнале сохраняйте число извлечённых элементов до и после дедупликации: разница показывает, возникли ли повторы на этапе нормализации.

Отсутствующее поле нужно оставлять пустым, а не заменять придуманным значением. Например, счётчик просмотров может отсутствовать в конкретной записи. Сохранение исходного JSON рядом с нормализованной строкой помогает позже проверить, потеряла ли информациясь при разборе или её не было в исходном ответе.

Минимальный запрос и нормализация на Python

Спецификация jsonscraper задаёт базовый адрес https://tiktok.evelode.com и передачу ключа в параметре запроса license_key. Пример ниже использует документированные параметры; ключ читается из переменной окружения и не выводится в журнал. Установите зависимость командой python -m pip install requests, затем задайте JSONSCRAPER_TIKTOK_LICENSE_KEY в окружении.

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

import requests

BASE_URL = "https://tiktok.evelode.com/searchVideo"
KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]


def extract_videos(payload):
    """Собрать видео из обеих известных структур search-ответа."""
    tiktok = payload.get("tiktok") or {}
    videos = []

    for item in tiktok.get("aweme_list") or []:
        if isinstance(item, dict):
            videos.append(item)

    for item in tiktok.get("search_item_list") or []:
        if isinstance(item, dict):
            aweme = item.get("aweme_info")
            if isinstance(aweme, dict):
                videos.append(aweme)

    return videos


def main():
    params = {
        "license_key": KEY,
        "keyword": "пример запроса о продукте",
        "count": 20,
        "region": "US",
    }
    response = requests.get(BASE_URL, params=params, timeout=30)
    response.raise_for_status()
    payload = response.json()

    if payload.get("status") != "ok":
        raise RuntimeError("API вернул внешний статус, отличный от ok")

    tiktok = payload.get("tiktok")
    if not isinstance(tiktok, dict):
        raise RuntimeError("В ответе отсутствует объект tiktok")

    if tiktok.get("status_code") != 0:
        raise RuntimeError("Внутренний status_code не равен успешному значению 0")

    raw_videos = extract_videos(payload)
    unique = {}
    for video in raw_videos:
        video_id = video.get("aweme_id")
        if video_id:
            unique.setdefault(str(video_id), video)

    snapshot = {
        "collected_at": datetime.now(timezone.utc).isoformat(),
        "keyword": params["keyword"],
        "status": payload.get("status"),
        "status_code": tiktok.get("status_code"),
        "raw_items": len(raw_videos),
        "unique_items": len(unique),
        "has_more": tiktok.get("has_more"),
        "cursor": tiktok.get("cursor"),
        "videos": list(unique.values()),
    }

    Path("snapshots").mkdir(exist_ok=True)
    stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
    Path(f"snapshots/{stamp}.json").write_text(
        json.dumps(snapshot, ensure_ascii=False, indent=2),
        encoding="utf-8",
    )

    print({
        "status": snapshot["status"],
        "status_code": snapshot["status_code"],
        "raw_items": snapshot["raw_items"],
        "unique_items": snapshot["unique_items"],
        "has_more": snapshot["has_more"],
    })


if __name__ == "__main__":
    main()

Скрипт проверяет транспортный уровень через raise_for_status(), затем проверяет внешний статус, наличие объекта tiktok и внутренний status_code. После этого он извлекает записи из двух структур поиска, дедуплицирует их по aweme_id и сохраняет снимок с временем сбора. Если подходящих записей нет, файл всё равно содержит сведения о запуске, что позволяет отличить сохранённый пустой результат от отсутствующего отчёта.

Как превратить снимки в сигнал для команды

Запускайте скрипт по расписанию средствами cron, CI или планировщика рабочего процесса. Для каждого запроса храните снимки отдельно либо добавляйте ключевое слово к имени файла. В таблицу состояния достаточно записывать время запуска, статус, число извлечённых и уникальных записей, а также флаг has_more. Уведомление полезно отправлять при исключении запроса, отсутствии обязательных частей ответа или резком изменении числа извлечённых записей относительно собственной истории.

Такое сравнение выявляет аномалию пайплайна, но само по себе не объясняет её причину. Меньшее число результатов может отражать состав текущей выдачи, а не поломку API или парсера. Поэтому полезно сохранять исходный JSON, сравнивать одинаковые параметры и проверять найденные идентификаторы. Порог уведомления выбирайте на основе наблюдений именно за вашим запросом, а не универсальной цифры.

Для пагинации используйте cursor из ответа и прекращайте обход, когда API сообщает об отсутствии следующих результатов. Сохраняйте использованные курсоры и параметры запроса, чтобы запуск можно было воспроизвести. Параметры date_posted и sort_by позволяют задавать временной фильтр и сортировку; если задача требует повторяемых сравнений, фиксируйте их между запусками.

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

После внедрения у команды появляется проверяемый ответ на три практических вопроса: состоялся ли запрос, где лежат результаты в JSON и сколько уникальных видео вошло в сохранённый снимок. Это сокращает путь от пустой таблицы до диагностики: сначала проверяются статусы и структура, затем — параметры, повторы и содержание исходного ответа.

Схема ответа и доступные поля могут различаться между записями. В live-проверке jsonscraper от 25 октября 2026 года поиск возвращал поля идентификатора, описания, автора и статистики; значения для конкретной записи следует считать необязательными. Рабочий отчёт хранит фактически полученные данные и не подменяет пропуски нулями.

Начать можно со страницы TikTok Scraper API, а точные маршруты и параметры сверить в официальной документации API. Такая проверка полезна перед запуском мониторинга: отчёт становится наблюдаемым результатом, качество которого можно диагностировать.