Щотижневий звіт про пошук у 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.
Як працює перевірка змін
- Запит повертає сторінку результатів пошуку за заданим ключовим словом.
- Нормалізатор збирає записи з
aweme_listіsearch_item_list[].aweme_info. - Скрипт усуває дублікати у відповіді за ID ролика.
- Ідентифікатори порівнюються з локальним JSON-журналом.
- Нові ID додаються до CSV, після чого весь знайдений набір зберігається для наступного запуску.


Візуалізація цього процесу корисна, коли передаєте скрипт колегам: 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; точні параметри пошуку звіряйте з офіційним довідником маршрутів.