jsonscraper
Рынки
К журналу

Как превратить TikTok-поиск в еженедельный журнал изменений

Python-скрипт сохраняет новые найденные видео, сверяет их по ID и формирует CSV для регулярной проверки тем

Редакционная политика Сообщить об ошибке

Еженедельный отчёт по TikTok-поиску полезен, когда он показывает, какие видео появились в очередной выборке после прошлого запуска. Для этого достаточно сохранять идентификаторы уже встреченных роликов и добавлять в CSV новые результаты. Ниже — воспроизводимый Python-сценарий с TikTok Scraper API: он запрашивает видео по ключевому слову, разбирает обе документированные формы ответа и ведёт локальную базу ID.

Задача: заметить новые записи, а не пересматривать всю выдачу

Команде поддержки, исследователю рынка или контент-аналитику может понадобиться регулярная выборка публичных видео по запросу о продукте. Если каждый раз выгружать результат целиком, повторяющиеся ролики затрудняют просмотр, а новые записи теряются среди уже обработанных. Журнал идентификаторов делает результат каждого запуска сравнимым: CSV содержит только новые для этого процесса видео и основные поля, которые вернулись в ответе.

Такой журнал отвечает на ограниченный, но практичный вопрос: какие элементы встретились в ответе текущего запуска и отсутствовали в сохранённом наборе ID? Это удобно для очереди ручного разбора и для передачи данных в таблицу или последующий анализ. Выборка отражает результаты API для заданного запроса; она сама по себе не описывает все публикации TikTok.

Что подготовить

  • Python 3.8 или новее.
  • Доступ к TikTok Scraper API и лицензионный ключ.
  • Запрос, который можно повторять без изменения смысла, например название продукта или конкретная фраза.

Сохраните ключ в переменной окружения JSONSCRAPER_TIKTOK_LICENSE_KEY, а не в файле со скриптом. В примере ниже ключ передаётся как параметр запроса license_key, согласно схеме API. Не выводите его в журнал выполнения.

export JSONSCRAPER_TIKTOK_LICENSE_KEY="ваш_ключ"
python -m pip install requests

В Windows PowerShell переменную можно задать для текущего сеанса так: $env:JSONSCRAPER_TIKTOK_LICENSE_KEY="ваш_ключ". Не добавляйте реальные секреты в Git или общий CSV.

Интеграция: запросить поиск и нормализовать JSON

Для поиска видео документация описывает GET-маршрут /searchVideo с обязательным параметром keyword. В запросе также можно задать count, регион, сортировку, временной фильтр и курсор для прокрутки результатов. В этом минимальном примере используются только ключевое слово, число запрашиваемых элементов и регион США. Справочник маршрутов TikTok API перечисляет точные имена параметров.

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

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

import requests

BASE_URL = "https://tiktok.evelode.com/searchVideo"
KEYWORD = "название продукта"
REGION = "US"
COUNT = 30
STATE_FILE = Path("seen_video_ids.json")
OUTPUT_FILE = Path("new_tiktok_videos.csv")

license_key = os.environ.get("JSONSCRAPER_TIKTOK_LICENSE_KEY")
if not license_key:
    raise RuntimeError("Задайте JSONSCRAPER_TIKTOK_LICENSE_KEY")

response = requests.get(
    BASE_URL,
    params={
        "license_key": license_key,
        "keyword": KEYWORD,
        "count": COUNT,
        "region": REGION,
    },
    timeout=60,
)
response.raise_for_status()
data = response.json()

# Пример ответа содержит внешний status и вложенный объект tiktok.
if "status" in data and data["status"] != "ok":
    raise RuntimeError("API вернул статус, отличный от ok")

tiktok = data.get("tiktok") or {}
items = list(tiktok.get("aweme_list") or [])
for entry in tiktok.get("search_item_list") or []:
    info = entry.get("aweme_info")
    if isinstance(info, dict):
        items.append(info)

# Уникальные элементы текущего ответа, сохраняя порядок.
current = {}
for item in items:
    video_id = item.get("aweme_id")
    if video_id:
        current[str(video_id)] = item

if STATE_FILE.exists():
    seen = set(json.loads(STATE_FILE.read_text(encoding="utf-8")))
else:
    seen = set()

new_items = [(video_id, item) for video_id, item in current.items()
             if video_id not in seen]
run_time = datetime.now(timezone.utc).isoformat()

fields = ["collected_at_utc", "query", "aweme_id", "created_at",
          "author", "description", "share_url", "play_count",
          "digg_count", "comment_count", "share_count"]
write_header = not OUTPUT_FILE.exists() or OUTPUT_FILE.stat().st_size == 0
with OUTPUT_FILE.open("a", newline="", encoding="utf-8") as f:
    writer = csv.DictWriter(f, fieldnames=fields)
    if write_header:
        writer.writeheader()
    for video_id, item in new_items:
        author = item.get("author") or {}
        stats = item.get("statistics") or {}
        writer.writerow({
            "collected_at_utc": run_time,
            "query": KEYWORD,
            "aweme_id": video_id,
            "created_at": item.get("create_time"),
            "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"),
        })

seen.update(current.keys())
STATE_FILE.write_text(json.dumps(sorted(seen)), encoding="utf-8")
print(f"В ответе: {len(current)} уникальных видео; новых: {len(new_items)}")

Скрипт записывает отсутствующие в JSON значения пустыми ячейками: поля и метрики могут не присутствовать в отдельной записи. Код не подменяет пропуск нулём и не трактует ноль как отсутствие данных. Время сбора отмечено отдельно от времени публикации, которое API возвращает в поле create_time.

Как устроена проверка изменений

  1. Запрос возвращает страницу результатов поиска по заданному ключевому слову.
  2. Нормализатор собирает записи из aweme_list и search_item_list[].aweme_info.
  3. Скрипт устраняет повторения внутри ответа по ID ролика.
  4. Идентификаторы сравниваются с локальным JSON-журналом.
  5. Новые ID добавляются в CSV, затем весь увиденный набор сохраняется для следующего запуска.
Article: Как превратить TikTok-поиск в еженедельный журнал изменений
Summary: Настройте повторяемый сбор TikTok-видео по ключевому запросу: обработайте обе формы ответа API, устраните дубли и сохраняйте только новые записи для недельного отчёта.
Image role: supporting illustration 2 — a different specific aspect
Section: Как устроена проверка изменений
Visual subject: Clear infographic in Russian showing five verified workflow stages with labels: Запрос / Два массива ответа / Дедупликация по awe
Схема показывает путь от ответа поиска до CSV новых записей и JSON-журнала для следующего запуска.© jsonscraper · создано с ИИ
Article: Как превратить TikTok-поиск в еженедельный журнал изменений
Summary: Настройте повторяемый сбор TikTok-видео по ключевому запросу: обработайте обе формы ответа API, устраните дубли и сохраняйте только новые записи для недельного отчёта.
Image role: cover — the central idea
Section: Как устроена проверка изменений
Visual subject: Editorial still life of a weekly data review: stacked transparent cards representing public short-video search results, one newly appearing card beside a compac
Новые для локального журнала идентификаторы отделяются от повторно найденных видео.© jsonscraper · создано с ИИ

Визуализация этого процесса полезна при передаче скрипта коллегам: CSV — это добавочный журнал, а JSON — состояние дедупликации. Их можно хранить отдельно от кода и резервировать совместно. Для командного или облачного запуска замените локальный JSON-файл подходящим постоянным хранилищем и предусмотрите атомарное обновление состояния, чтобы параллельные запуски не перезаписывали друг друга.

Повторный запуск и пагинация

Повторяйте запуск по расписанию планировщиком операционной системы, CI-задачей или рабочим процессом автоматизации. Не меняйте ключевое слово без записи его версии: разные запросы образуют разные выборки, и смешивание их в одном журнале усложняет интерпретацию. Для простоты приведённый скрипт использует один запрос; список запросов можно обрабатывать циклом, сохраняя поле query для каждой строки.

API поддерживает cursor для прокрутки поисковых результатов. Если добавляете пагинацию, передавайте курсор из предыдущего ответа, храните его как непрозрачное значение и прекращайте обход, когда дальнейшие страницы не нужны. Ограничение count задаёт число запрашиваемых элементов, но фактическое число записей следует определять по ответу. Даже несколько страниц остаются полученными страницами поиска, а не гарантией полного охвата платформы.

В текущем сценарии намеренно нет автоматической классификации текста или вывода о «тренде». CSV помогает быстро выделить новые найденные записи; аналитик может затем разметить их по теме, намерению или типу вопроса и проверить примеры вручную. Если подключаете языковую модель, передавайте ей только нужные текстовые поля и просите возвращать категории вместе с исходным ID, чтобы результат можно было проверить и связать с записью.

Проверки и типичные ошибки

  • HTTP-ошибка. raise_for_status() останавливает выполнение при коде HTTP вне успешного диапазона. Проверьте доступность API, параметры и учётную запись, прежде чем обновлять файл состояния.
  • Статус API отличается от ok. Скрипт останавливается до записи результатов, если в ответе присутствует верхнеуровневое поле status с другим значением. Это сохраняет предыдущий журнал и помогает не принять ошибочный ответ за пустую выдачу.
  • Пустой список в aweme_list. Проверьте также search_item_list; код учитывает обе структуры.
  • Видео повторяются между запусками. Это ожидаемо для перекрывающихся страниц поисковой выдачи: в отчёт они повторно не попадают, если ID уже сохранён.
  • Метрика отсутствует. Ячейка остаётся пустой. При расчётах отделяйте отсутствующие значения от фактических нулей.
  • Состояние потеряно. Скрипт сочтёт все возвращённые ID новыми. Резервируйте seen_video_ids.json вместе с CSV либо используйте постоянную БД.

При автоматизации сохраняйте диагностические сведения без ключа: время запуска, HTTP-код, API-статус, число разобранных записей и число новых ID. Это помогает отличить отсутствие новых видео от неудачного запроса. Исходный полный ответ можно архивировать отдельно, если требуется последующая перепроверка схемы; ограничьте доступ и срок хранения согласно задачам команды.

Результат

После запуска у вас есть CSV с новыми для журнала ID роликами, описаниями, ссылками и доступными публичными полями, а также JSON-состояние для сравнения со следующим запуском. Такой результат подходит как компактная входная очередь для поддержки, аналитики или контент-команды. Посмотреть описание API и варианты доступа можно на странице TikTok Scraper API; точные параметры поиска сверяйте с официальным справочником маршрутов.

Персоны

Для этой статьи персоны пока не указаны.

Читайте дальшеКак выявить повторяющиеся вопросы о продукте в TikTok
Читать следующую статью

Превратите прочитанное в рабочую интеграцию

Изучайте API социальных данных jsonscraper, тестируйте запросы и создавайте новые процессы.

Смотреть API