Michael JohnsonПісля запуску застосунку або нової функції відгуки швидко розпорошуються короткими відео. Маркетолог вручну знаходить кілька роликів і пересилає посилання в чат, а аналітик згодом не може зрозуміти, які публікації вже враховано та як змінювалися перегляди. Практичне рішення — регулярно збирати результати пошуку за кількома сталими запитами, зберігати вихідні відповіді й формувати звіт на основі підтверджених полів.
У цьому посібнику налаштуємо збір для конкретного випадку: команда випустила нову функцію й хоче щотижня відстежувати публічні відео TikTok, в описах яких згадано назву продукту, ключову функцію або типову проблему користувача. Це моніторинг результатів пошукової вибірки: API повертає результати за запитом і параметрами, а не гарантований перелік усіх публікацій про запуск.
Спершу визначте, який сигнал потрібен команді
Велика кількість переглядів сама по собі мало пояснює, що робити далі. Команді корисніше знати, які запитання повторюються, які сценарії демонструють люди та які ролики отримують помітну публічну реакцію. Тож спочатку сформулюйте кілька пошукових фраз і вирішіть, які поля потраплять до звіту.
Наприклад, для запуску інструмента планування публікацій можна перевірити запити «назва продукту», «планувальник контенту» та «як запланувати TikTok». Фрази мають відображати різні способи, якими люди можуть описувати ту саму тему. Запишіть їх разом із датою початку моніторингу й регіоном, щоб надалі порівнювати вивантаження з однаковими налаштуваннями.
Мінімальна таблиця може містити час збору, пошукову фразу, ідентифікатор відео, посилання, опис, ім’я автора, ідентифікатор автора та доступні значення переглядів, уподобань і коментарів. TikTok Scraper API документує для результатів пошуку такі поля, як aweme_id, desc, share_url, дані про автора й частину статистики. Наявність конкретного поля потрібно перевіряти в кожному об’єкті: окремі метрики можуть бути відсутні.
Під’єднайте документований пошук
Для пошуку відео використовуйте GET-маршрут /searchVideo за базовою адресою https://tiktok.evelode.com. У документації зазначено обов’язковий параметр keyword і додаткові параметри count, cursor, date_posted, sort_by, region і cache_timeout. Допустимі значення фільтра дати включають this-week, а сортування — relevance, most-liked і date-posted. Їхнє призначення та назви перевіряйте у довіднику маршрутів TikTok API.
Ліцензійний ключ передається як параметр запиту license_key. У робочому скрипті зчитуйте його зі змінної середовища JSONSCRAPER_TIKTOK_LICENSE_KEY, не записуйте секрет у вихідний код і не виводьте його в журнали. Цей приклад розрахований на Python 3.8+ і використовує пакет requests:
import os
import requests
BASE_URL = "https://tiktok.evelode.com"
API_KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
def search_videos(keyword, cursor=None):
params = {
"license_key": API_KEY,
"keyword": keyword,
"count": 20,
"date_posted": "this-week",
"sort_by": "date-posted",
"region": "US",
}
if cursor is not None:
params["cursor"] = cursor
response = requests.get(
f"{BASE_URL}/searchVideo",
params=params,
timeout=30,
)
response.raise_for_status()
payload = response.json()
if payload.get("status") != "ok":
raise RuntimeError("TikTok API повернув статус, відмінний від ok")
return payload["tiktok"]
result = search_videos("content planning app")
print("Знайдені об’єкти:", len(result.get("aweme_list", [])))Скрипт перевіряє HTTP-помилки й зовнішній статус відповіді. Успішна HTTP-відповідь сама по собі не гарантує, що пошук містить відео: за порожньої вибірки список може бути порожнім. Під час першого запуску корисно зберегти відповідь цілком у захищеному сховищі, щоб зіставити реальні об’єкти з таблицею нормалізованих полів.
Опрацюйте обидва формати відповіді пошуку
У результатах пошуку є важлива особливість структури. Відео можуть міститися безпосередньо в tiktok.aweme_list, а можуть надходити всередині tiktok.search_item_list[].aweme_info. Якщо обробник читає лише перший список, він може пропустити результати, наявні у другому форматі.
Додайте невеликий нормалізатор, який підтримує обидві структури й без проблем пропускає елементи без вкладеного об’єкта відео:
def extract_awemes(tiktok):
items = list(tiktok.get("aweme_list") or [])
for item in tiktok.get("search_item_list") or []:
aweme = item.get("aweme_info")
if aweme:
items.append(aweme)
return items
def normalize(aweme, keyword, collected_at):
author = aweme.get("author") or {}
stats = aweme.get("statistics") or {}
return {
"collected_at": collected_at,
"keyword": keyword,
"video_id": aweme.get("aweme_id"),
"posted_at": aweme.get("create_time"),
"description": aweme.get("desc"),
"share_url": aweme.get("share_url"),
"author_id": author.get("uid"),
"author_name": author.get("nickname"),
"views": stats.get("play_count"),
"likes": stats.get("digg_count"),
"comments": stats.get("comment_count"),
"shares": stats.get("share_count"),
}Якщо значення відсутнє, залишайте None. Не замінюйте його нулем: нуль означає виміряне значення, тоді як None зберігає факт, що поле не надійшло. Ця різниця впливає на середні значення, частки й будь-які висновки для команди.
Зберігайте історію, а не лише поточний знімок
Щоб бачити динаміку, зберігайте окремі записи спостережень. Ідентифікатор відео підходить для дедуплікації публікацій, але не для видалення історії: повторна поява того самого ролика під час наступного збору дає нову точку спостереження. Наприклад, унікальний ключ таблиці спостережень можна скласти з video_id і collected_at, а посилання та опис зберігати в записі для зручної перевірки.
Для прототипу стане в пригоді мінімальна схема SQLite:
import sqlite3
conn = sqlite3.connect("tiktok_observations.sqlite3")
conn.execute("""
CREATE TABLE IF NOT EXISTS observations (
video_id TEXT NOT NULL,
collected_at TEXT NOT NULL,
keyword TEXT NOT NULL,
posted_at INTEGER,
description TEXT,
share_url TEXT,
author_id TEXT,
author_name TEXT,
views INTEGER,
likes INTEGER,
comments INTEGER,
shares INTEGER,
PRIMARY KEY (video_id, collected_at, keyword)
)
""")
conn.commit()На практиці нормалізуйте час збору до UTC, зберігайте вихідний JSON окремо й додайте стовпець версії схеми. Вихідна відповідь допоможе повторно перевірити перетворення, якщо структура нових об’єктів відрізняється від звичної. Для публікацій, знайдених за кількома запитами, зберігайте збіжні ключові фрази в окремій пов’язаній таблиці або об’єднуйте їх під час формування звіту.
Пагінація: продовжуйте лише за курсором із відповіді
Параметр cursor призначений для продовження пошуку. Його значення береться з попередньої відповіді й передається без змін, а робота завершується, коли has_more більше не вказує на продовження або досягнуто встановлений ліміт. Курсор слід вважати непрозорим: не обчислюйте його самостійно й не замінюйте лічильником сторінок.
def collect_pages(keyword, max_pages=3):
cursor = None
collected = []
for _ in range(max_pages):
page = search_videos(keyword, cursor)
collected.extend(extract_awemes(page))
if not page.get("has_more"):
break
cursor = page.get("cursor")
if cursor is None:
break
return collectedОбмеження кількості сторінок робить регулярне завдання передбачуваним за кількістю запитів. Записуйте кількість сторінок і значення has_more у журнал виконання: це дає контекст для звіту про вибірку. Навіть із пагінацією результат описує отримані відповіді API та заданий ліміт збору; він не є оцінкою всіх публікацій на платформі.
Створіть відтворюваний звіт
Запускайте збір за розкладом раз на тиждень або частіше, якщо команді потрібні сигнали з меншою затримкою. Для кожного запуску фіксуйте перелік запитів, параметри, час, кількість отриманих об’єктів і кількість унікальних ідентифікаторів. Окремо рахуйте публікації, уперше помічені під час цього запуску, та ті, що траплялися раніше.
У звіті стануть у пригоді чотири прості подання:
- Нові відео: посилання, описи, дата публікації та пошукова фраза, за якою знайдено ролик.
- Повторювані теми: групування описів за категоріями, визначеними вручну, наприклад «помилка налаштування», «запит на функцію» та «огляд сценарію».
- Публічні реакції: доступні перегляди, уподобання, коментарі й поширення, наведені поруч із часом спостереження.
- Сигнали для перевірки: нові формулювання, поширені запитання або ролики, які варто переглянути співробітнику.
Не називайте різницю між двома знімками «новими вподобаннями», не перевіривши семантику й актуальність значень у відповіді. Коректніше формулювати так: «значення метрики в останній отриманій відповіді» та «різниця між збереженими знімками». Так команда бачить, що саме розраховано, і може відкрити вихідну публікацію, перш ніж ухвалювати рішення.
Додайте ШІ на етап класифікації, а не замість збору
Після нормалізації можна передати описи відео моделі для класифікації за заздалегідь визначеними категоріями. Надсилайте лише потрібні текстові поля й просіть повернути структурований результат: категорію, коротке обґрунтування, рівень упевненості та фрагмент опису, на якому ґрунтується мітка. Зберігайте вихідну публікацію поруч із міткою, щоб аналітик міг перевірити спірні випадки.
Робоча схема залишається простою: планувальник запускає збір; Python перевіряє відповідь і зберігає JSON; окреме завдання нормалізує нові записи; класифікатор обробляє лише нові описи; звіт формується з бази й надсилається в обраний командою канал. Сам TikTok Scraper API надає дані пошуку, а класифікація та доставка звіту — це ваша інтеграційна логіка, яку можна реалізувати в Python, n8n або Make.
Щоб зменшити шум, визначте словник категорій до надсилання даних моделі й періодично перевіряйте вручну розмічену вибірку. Для коротких або неоднозначних описів корисний статус «недостатньо контексту», а не примусовий вибір категорії. Мітки ШІ допомагають упорядкувати чергу на перегляд, тоді як висновки про проблему користувача слід підтверджувати читанням публікацій і зіставленням кількох спостережень.
Помилки, повторні спроби й безпечне поводження з ключем
Мережевий запит може завершитися тайм-аутом, тимчасовою помилкою або відповіддю, яку не вдалося розібрати як JSON. Розділіть обробку на етапи: запит, перевірка HTTP-коду, розбір JSON, перевірка зовнішнього статусу, нормалізація та запис. У разі тимчасових збоїв використовуйте обмежену кількість повторних спроб зі збільшенням паузи; постійні помилки записуйте для подальшого розгляду й не позначайте запуск як успішний.
Зберігайте ключ у менеджері секретів середовища виконання або змінній середовища. Оскільки API приймає license_key у рядку запиту, не журналюйте повний URL і параметри запиту: у них опиниться секрет. Для діагностики записуйте маршрут, код відповіді, тривалість, пошукову фразу й ідентифікатор завдання, вилучаючи ключ із журналів.
Встановлюйте розклад і обсяг вибірки відповідно до свого завдання та умов використання платформи. Збір публічних даних варто обмежити тим, що справді потрібно для аналізу; зберігання описів, посилань та ідентифікаторів авторів слід описати у внутрішніх правилах команди. Відповіді API й метрики можуть бути неповними або змінюватися між спостереженнями, тому звіт має зберігати час збору та походження кожного рядка.
Результат: від ручних посилань до історії, яку можна перевірити
Після налаштування команда отримує регулярно оновлюваний список знайдених роликів, вихідні відповіді для аудиту, таблицю доступних публічних метрик і огляд повторюваних тем. Це допомагає швидше помічати запитання про нову функцію, знаходити приклади користувацьких сценаріїв і добирати публікації для ручного аналізу. Порівняння знімків показує, як змінюються збережені значення для вже знайдених роликів, а журнал запитів пояснює, у який спосіб сформувалася вибірка.
Почніть з одного запиту й невеликого ліміту сторінок, перевірте реальну структуру відповіді, а потім додайте інші формулювання та розклад. Перш ніж переносити прототип у виробниче середовище, визначте правила дедуплікації, зберігання й обробки помилок. Актуальні маршрути й параметри доступні в офіційній документації API; опис можливостей і перехід до тестування — на сторінці TikTok Scraper API.
