TikTok: превратите поисковую выдачу в еженедельный список тем для поддержки

Команде поддержки нужен список публичных TikTok-видео, где люди обсуждают непонятную функцию или задают вопросы о продукте. Ручной поиск трудно повторять одинаково, а API-ответы поиска могут хранить ролики в разных местах JSON. Ниже — минимальный Python-сценарий, который запрашивает результаты по ключевым словам, объединяет обе структуры, убирает повторы по ID и сохраняет найденные записи в CSV.

Какой результат даст сценарий

На выходе получится таблица с ID ролика, ссылкой, описанием, временем публикации, автором и доступными счетчиками реакций. Поддержка или маркетинг смогут вручную отметить, какие темы требуют ответа, обновления инструкции или проверки в собственной CRM. Таблица отражает именно возвращённые API результаты по заданным запросам; считайте её рабочей выборкой для разбора, а не исчерпывающим каталогом всех обсуждений.

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

Что запрашивать и как устроен ответ

Для поиска роликов jsonscraper документирует GET-маршрут /searchVideo на хосте https://tiktok.evelode.com. Обязательный параметр — keyword; можно передать count, регион, сортировку, период публикации и курсор следующей страницы. Например, поиск можно повторять по нескольким заранее определённым фразам: названию функции, распространённой формулировке ошибки и короткому вопросу о настройке. Параметры и их допустимые значения перечислены в справочнике TikTok API.

У поиска есть важная особенность для парсера: массив aweme_list может оказаться пустым, тогда как найденные объекты лежат в search_item_list, внутри каждого — aweme_info. Поэтому обработчик ниже проверяет обе формы. Пример ответа и поля, наблюдавшиеся в проверке 25 октября 2026 года, приведены в первичной спецификации jsonscraper; поля статистики могут отсутствовать, поэтому код не подставляет выдуманные значения.

Подготовьте ключ и список запросов

Сохраните ключ в переменной окружения JSONSCRAPER_TIKTOK_LICENSE_KEY, а не в исходном файле. В командной оболочке Linux или macOS это можно сделать так:

export JSONSCRAPER_TIKTOK_LICENSE_KEY="ваш_ключ"

Установите библиотеку запросов, подготовьте файл queries.txt с одним поисковым выражением на строку, например название продукта настройка и название функции не работает. Формулировки следует выбирать по языку аудитории и вести отдельным списком, чтобы еженедельные выгрузки сравнивали одни и те же запросы.

python -m pip install requests

Соберите и нормализуйте найденные ролики

Пример совместим с Python 3.8+. Он делает один запрос для каждой фразы с лимитом результатов, проверяет HTTP-ошибки и верхний статус, а затем сохраняет только реально присутствующие поля. Повторные совпадения объединяются по aweme_id, а все запросы, по которым найден ролик, записываются в поле keywords. Отдельное поле collected_at_utc фиксирует время получения данных для сопоставления следующих запусков.

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

import requests

BASE_URL = "https://tiktok.evelode.com/searchVideo"
API_KEY = os.environ.get("JSONSCRAPER_TIKTOK_LICENSE_KEY")

if not API_KEY:
    raise SystemExit("Установите JSONSCRAPER_TIKTOK_LICENSE_KEY")


def get_items(tiktok):
    """Извлекает видео из обеих документированных форм ответа поиска."""
    items = list(tiktok.get("aweme_list") or [])
    for entry in tiktok.get("search_item_list") or []:
        info = entry.get("aweme_info") if isinstance(entry, dict) else None
        if info:
            items.append(info)
    return items


with open("queries.txt", encoding="utf-8") as query_file:
    queries = [line.strip() for line in query_file if line.strip()]

collected_at = datetime.now(timezone.utc).isoformat()
videos = {}

for keyword in queries:
    response = requests.get(
        BASE_URL,
        params={
            "license_key": API_KEY,
            "keyword": keyword,
            "count": 30,
            "region": "US",
            "sort_by": "relevance",
        },
        timeout=30,
    )
    response.raise_for_status()
    payload = response.json()

    if payload.get("status") != "ok":
        print("Неуспешный статус API для запроса:", keyword, file=sys.stderr)
        continue

    tiktok = payload.get("tiktok") or {}
    for item in get_items(tiktok):
        video_id = item.get("aweme_id")
        if not video_id:
            continue

        if video_id not in videos:
            author = item.get("author") or {}
            stats = item.get("statistics") or {}
            videos[video_id] = {
                "aweme_id": video_id,
                "keywords": [keyword],
                "description": item.get("desc"),
                "share_url": item.get("share_url"),
                "create_time": item.get("create_time"),
                "author": author.get("unique_id") or author.get("nickname"),
                "play_count": stats.get("play_count"),
                "digg_count": stats.get("digg_count"),
                "comment_count": stats.get("comment_count"),
                "share_count": stats.get("share_count"),
                "collected_at_utc": collected_at,
            }
        elif keyword not in videos[video_id]["keywords"]:
            videos[video_id]["keywords"].append(keyword)

columns = [
    "aweme_id", "keywords", "description", "share_url", "create_time",
    "author", "play_count", "digg_count", "comment_count", "share_count",
    "collected_at_utc",
]
with open("tiktok_support_review.csv", "w", newline="", encoding="utf-8-sig") as output:
    writer = csv.DictWriter(output, fieldnames=columns)
    writer.writeheader()
    for video in videos.values():
        row = dict(video)
        row["keywords"] = " | ".join(row["keywords"])
        writer.writerow(row)

print("Сохранено найденных уникальных роликов:", len(videos))

Запрос отправляется через параметр params, поэтому библиотека корректно кодирует текстовые фразы в URL. Ключ при этом находится в query-параметре, как описано в документации; не печатайте полный URL запроса в журнал приложения. Для диагностики сохраняйте код HTTP-ответа, название поисковой фразы и время запуска, но исключайте секреты и персональные данные, которые не нужны задаче.

Как читать CSV без ложных выводов

Столбец keywords содержит все фразы, по которым был найден ролик; collected_at_utc позволяет отличить время публикации от времени сбора. ID удобен для дедупликации, а ссылка — для проверки человеком. Пустой счетчик означает, что поле отсутствовало в конкретном ответе, а не нулевое значение.

Для первой сортировки добавьте в рабочую копию CSV колонки тема, тип сигнала, нужен ответ и ссылка на внутренний материал. Варианты темы должны соответствовать вашему продукту: например, установка, оплата, совместимость или устранение ошибки. Такая схема превращает выгрузку в очередь разбора и сохраняет возможность проверить решение по исходному ролику.

Запустите сбор по расписанию

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

Параметр cursor предусмотрен для прокрутки выдачи; передавать его нужно из ответа предыдущего вызова. В приведённом минимальном варианте пагинация намеренно не включена: ограниченный набор запросов проще проверить и воспроизвести. Если вы добавите страницы, храните курсор непрозрачно, останавливайтесь по флагу наличия продолжения и задайте верхний предел вызовов на один запуск. Запрос API возвращает выборку; не интерпретируйте число строк как полный охват TikTok.

Практические границы применения

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

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