Michael JohnsonДві команди запускають ролики про схожий продукт, але оцінюють їх вручну за різними ознаками: одна запам’ятовує перегляди, друга — коментарі, а третя зберігає посилання в чаті. Через тиждень важко зрозуміти, які формати повторюються у конкурентів, які публікації отримують помітну реакцію та що змінилося від часу попереднього перегляду.
Рішення — збирати обмежену й відтворювану вибірку публічних відео за заздалегідь визначеними ключовими словами, зберігати вихідний JSON і створювати таблицю з однаковими полями. Це дає змогу порівнювати ролики в одному робочому процесі, а не змішувати випадкові спостереження з висновками про ринок. Нижче — схема для невеликого моніторингу конкурентів на Python за допомогою TikTok Scraper API від jsonscraper.
Спочатку визначте питання для аналізу
Збір даних корисний, коли заздалегідь зрозуміло, яке рішення буде ухвалено за його результатами. Наприклад, маркетингова команда виробника спортивної пляшки хоче зрозуміти, як конкуренти показують продукт у коротких роликах: через демонстрацію використання, розпакування, порівняння чи реакцію користувачів. Для цього не потрібно копіювати весь TikTok. Достатньо кількох цільових пошукових запитів і повторюваного спостереження за відео, які API повертає для цих запитів.
Сформулюйте питання так, щоб його можна було перевірити: «Які формати описів і демонстрацій трапляються серед опублікованих роликів за нашими п’ятьма ключовими фразами та які з знайдених відео зараз мають найбільше переглядів і реакцій?» Таке формулювання розділяє два рівні аналізу. Текст і опис допомагають згрупувати творчі підходи; лічильники переглядів, уподобань, коментарів і поширень дають знімок публічної реакції на момент збору.
Цей знімок корисний для визначення пріоритетів під час ручного перегляду й відстеження змін. Він описує ролики, повернуті для конкретних запитів, параметрів і часу запуску. Тому коректний висновок звучить так: «у нашій вибірці часто трапляються розпакування» або «у цієї групи роликів зараз вища медіана переглядів». Саме такий масштаб аналізу допомагає команді обирати гіпотези для власного контенту.
Спроєктуйте невеликий конвеєр даних
Розділіть роботу на чотири етапи: збір, збереження сирої відповіді, нормалізація й аналіз. Під час збору API опитують для кожного затвердженого ключового слова. Сиру відповідь зберігають повністю, щоб її можна було повторно перевірити. Нормалізація перетворює вкладену структуру JSON на рядки таблиці, а аналітика обчислює метрики й групує ролики за ключовими словами або форматами, призначеними вручну.
- Збір. Запитуйте визначену кількість результатів для кожного ключового слова з однаковими регіоном і сортуванням.
- Архів. Записуйте вихідний JSON і час отримання, щоб можна було перевірити витягнуті значення.
- Нормалізація. Залиште ідентифікатор відео, посилання, опис, автора, час публікації та доступні лічильники.
- Контроль якості. Видаляйте дублікати за ID, позначайте відсутні значення та зберігайте ключове слово, за яким знайдено ролик.
- Порівняння. Обчислюйте власні показники лише з доступних вихідних полів і порівнюйте групи в межах одного знімка.
Такий підхід кращий за список посилань, бо зберігає походження кожного рядка й дає змогу відрізнити повторну появу того самого ролика від нового матеріалу. Також зберігайте дату збору: публічні лічильники можуть змінюватися, тож значення з сьогоднішньої відповіді не можна трактувати як постійну характеристику відео.
Що підтримує TikTok Scraper API
Для пошуку відео за текстовим запитом документація jsonscraper описує GET-маршрут /searchVideo за базовою адресою https://tiktok.evelode.com. Обов’язковий параметр — keyword; також доступні count, cursor, region, date_posted, sort_by і cache_timeout. У документації наведено варіанти сортування most-liked, relevance і date-posted, а серед періодів публікації — yesterday, this-week, this-month, last-3-months, last-6-months і all-time. Перевірте назви параметрів і їх призначення у довіднику маршрутів TikTok.
Ключ передається в параметрі запиту license_key. Для робочого скрипту збережіть його в змінній середовища JSONSCRAPER_TIKTOK_LICENSE_KEY, а не у вихідному файлі, таблиці чи журналі запуску. У відповіді перевіряйте верхньорівневий status, а потім розбирайте об’єкт tiktok. Для пошуку структура може містити список aweme_list, а також search_item_list, де відомості про ролик розміщені всередині aweme_info. Наведений нижче код підтримує обидві форми.
У підтверджених спостереженнях за відповідями пошуку є ID ролика, опис, час публікації, посилання, відомості про автора та метрики на кшталт переглядів, уподобань, коментарів, збережень і поширень. У конкретному записі поля можуть бути відсутні. У таблиці такі значення слід залишати порожніми, а не замінювати нулем: нуль означає виміряне значення, порожнє поле — відсутність значення в отриманому об’єкті.
Мінімальний приклад на Python
Наведений нижче скрипт виконує один запит для кожного ключового слова, зберігає повну відповідь у JSON-файлі й формує CSV для таблиці або подальшої обробки. Він розрахований на Python 3.8+ і використовує лише стандартну бібліотеку. Перед запуском задайте змінну середовища з ліцензійним ключем. Налаштуйте список ключових слів і кількість результатів відповідно до свого сценарію.
import csv
import json
import os
import time
from datetime import datetime, timezone
from pathlib import Path
from urllib.parse import urlencode
from urllib.request import urlopen
BASE_URL = "https://tiktok.evelode.com/searchVideo"
LICENSE_KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
KEYWORDS = ["термобутылка", "спортивная бутылка", "распаковка бутылки"]
REGION = "US"
COUNT = 20
def request_search(keyword):
params = {
"license_key": LICENSE_KEY,
"keyword": keyword,
"count": COUNT,
"region": REGION,
"sort_by": "relevance",
"date_posted": "this-month",
}
url = BASE_URL + "?" + urlencode(params)
with urlopen(url, timeout=60) as response:
return json.loads(response.read().decode("utf-8"))
def extract_videos(payload):
if payload.get("status") != "ok":
raise RuntimeError("API returned a non-ok status")
tiktok = payload.get("tiktok") or {}
rows = []
for item in tiktok.get("aweme_list") or []:
if isinstance(item, dict):
rows.append(item)
for item in tiktok.get("search_item_list") or []:
video = item.get("aweme_info") if isinstance(item, dict) else None
if isinstance(video, dict):
rows.append(video)
return rows, tiktok
Path("raw").mkdir(exist_ok=True)
seen = set()
records = []
for keyword in KEYWORDS:
payload = request_search(keyword)
collected_at = datetime.now(timezone.utc).isoformat()
safe_name = keyword.replace(" ", "_")
raw_path = Path("raw") / (safe_name + ".json")
raw_path.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
videos, tiktok = extract_videos(payload)
for video in videos:
video_id = video.get("aweme_id")
if not video_id:
continue
dedupe_key = (keyword, video_id)
if dedupe_key in seen:
continue
seen.add(dedupe_key)
stats = video.get("statistics") or {}
author = video.get("author") or {}
records.append({
"collected_at": collected_at,
"keyword": keyword,
"video_id": video_id,
"url": video.get("share_url"),
"created_at_epoch": video.get("create_time"),
"description": video.get("desc"),
"author": author.get("nickname"),
"username": author.get("unique_id"),
"views": stats.get("play_count"),
"likes": stats.get("digg_count"),
"comments": stats.get("comment_count"),
"shares": stats.get("share_count"),
"saves": stats.get("collect_count"),
"cursor": tiktok.get("cursor"),
})
time.sleep(1)
fieldnames = [
"collected_at", "keyword", "video_id", "url", "created_at_epoch",
"description", "author", "username", "views", "likes", "comments",
"shares", "saves", "cursor",
]
with open("tiktok_creatives.csv", "w", newline="", encoding="utf-8") as output:
writer = csv.DictWriter(output, fieldnames=fieldnames)
writer.writeheader()
writer.writerows(records)
print("Saved", len(records), "video rows to tiktok_creatives.csv")Скрипт зберігає ключове слово поруч із відео: це важливо, якщо один ролик знайдено за кількома запитами. Тут дедуплікація виконується в межах кожного ключового слова, тому один ID може займати окремий рядок для різних запитів. Щоб отримати єдину таблицю без повторів, замініть ключ (keyword, video_id) на video_id, а ключові слова накопичуйте у списку або окремій таблиці зв’язків.
Код навмисно виконує один запит для кожного слова й автоматично не перебирає сторінки. Якщо потрібна наступна сторінка, документація визначає cursor як значення для прокручування результатів, отримане з попередньої відповіді. Передавайте його як непрозоре значення, не обчислюючи самостійно. Для конкретного робочого процесу перевірте схему пагінації на тестовій відповіді й зупиняйтеся, коли немає нових результатів або наступного курсора.
Як отримати порівнювану таблицю
CSV можна відкрити в електронній таблиці, завантажити в базу даних або використати в Python для обчислення агрегованих показників. Для первинного звіту згрупуйте рядки за датою збору, ключовим словом і форматом ролика. Формат краще позначати після перегляду опису й самого відео: наприклад, «демонстрація», «розпакування», «відгук», «порівняння». Класифікацію можна виконати вручну на невеликій вибірці або попросити модель підготувати попередню розмітку з подальшою перевіркою людиною.
Якщо автоматично розмічаєте тексти, передавайте моделі лише потрібні поля — наприклад, опис та ідентифікатор — і просіть повернути одну мітку з заздалегідь затвердженого списку. Зберігайте вихідний опис окремо від результату класифікації. Так аналітик зможе перевірити спірну мітку й повторно сформувати звіт після зміни таксономії, не надсилаючи повторний запит до API.
Для порівняльних метрик використовуйте значення, зібрані в один час. Наприклад, співвідношення вподобань до переглядів можна обчислити як likes / views, якщо обидва поля наявні, а кількість переглядів більша за нуль. Так само можна порахувати частку коментарів або поширень. Ці співвідношення описують поточні публічні лічильники конкретного відео; вони не вимірюють охоплення певної аудиторії, догляди до кінця чи конверсії. Для бізнес-рішень зіставляйте їх із власною кампанією та використовуйте як орієнтир для вибору ідей, а не як обіцянку результату від повторення чужого формату.
Медіана часто зручніша за середнє, якщо у вибірці є кілька дуже популярних роликів. Порівнюйте медіану переглядів і медіану реакцій у групах лише за однакового правила збору: того самого набору запитів, регіону, часового фільтра та приблизно однакового часу знімка. Записуйте параметри запуску разом із датою. Якщо зміна пошуку або вибірки впливає на склад рядків, різниця між двома звітами може відображати також зміну методу.
Повторний запуск і контроль змін
Щоб перетворити одноразовий аналіз на моніторинг, запускайте скрипт за розкладом — наприклад, щодня або щотижня — і додавайте дату збору до кожного запису. Для кожного ролика зберігайте пари «час знімка — значення лічильника». Тоді можна побачити, як змінилися публічні показники між спостереженнями, зберігаючи кожну точку вимірювання окремо. Не перезаписуйте старі лічильники поточними, інакше динаміка зникне.
У робочому середовищі перенесіть сирий JSON із локальної папки до об’єктного сховища або іншої системи архівування, а нормалізовані рядки — до бази даних з унікальним ключем, наприклад поєднанням ID відео й часу збору. Додайте журнал помилок без секретного ключа, обмежте кількість повторів і налаштуйте сповіщення про невдалий запит. Після тимчасової помилки запит можна повторити із затримкою; у разі структурної помилки краще зберегти відповідь і позначити запуск як такий, що потребує перевірки, щоб збій не перетворився на непомітно порожній звіт.
Не використовуйте значення cursor як постійний ідентифікатор дослідження: це маркер продовження видачі. Зберігайте його разом із параметрами відповідного запиту, використовуйте лише для продовження цієї видачі й не змішуйте сторінки з різних ключових слів. Також фіксуйте фактичну кількість оброблених результатів: запитане значення count задає бажаний розмір відповіді, але не гарантує повного охоплення всіх відповідних публікацій.
Як розширити робочий процес
Якщо пошукова вибірка надто зашумлена, можна окремо відстежувати конкретні відкриті профілі або хештеги. У документації є маршрути /getUserFeed і /getHashtagFeed із параметрами запиту та пагінації. Це інші вибірки з власними правилами продовження: для стрічки профілю використовується max_cursor, для хештегу — cursor. Підключайте їх як окремі джерела й зберігайте тип джерела та параметри, щоб не змішувати результати пошуку за ключовим словом із публікаціями профілю чи хештегу.
Якщо команда не має власної інфраструктури, CSV можна передавати в Google Sheets через API: документація Google Sheets API описує читання й запис значень клітинок. Додайте окремі аркуші для сирих запусків, нормалізованих роликів і зведення. Цей варіант зручний для спільного маркування; коли обсяг історії стане завеликим для таблиці, перенесіть рядки до SQL-сховища, зберігши ті самі поля та походження даних.
Для AI-агента доречною роллю буде підготувати стислий підсумок уже зібраних і нормалізованих записів: згрупувати описи, запропонувати формати й виділити незвичні значення. Не варто доручати агенту формулювати факти про всю платформу на підставі невеликої видачі. Передавайте йому період, список запитів і кількість рядків, просіть посилатися на ID відео та повертати невизначені або відсутні поля порожніми. Потім аналітик перевіряє приклади за збереженими посиланнями.
Що буде на виході
Після налаштування команда отримає відтворюваний реєстр знайдених відео з ідентифікаторами, посиланнями, описами, авторами, часом публікації та доступними публічними лічильниками. Збережена сира відповідь дає змогу перевірити перетворення, а CSV — швидко сортувати ролики, фільтрувати їх за ключовими словами й порівнювати знімки за датами. На цій основі можна підготувати щотижневе зведення: які формати повторювалися, які публікації варто переглянути та які творчі гіпотези слід протестувати у власному контенті.
Практичний результат — не універсальний рейтинг конкурентів, а впорядкована вибірка з чітко визначеним походженням. Її якість залежить від вибраних запитів, фільтрів і періоду спостереження. Тому зберігайте параметри збору, вручну перевіряйте окремі ролики й відокремлюйте доступні метрики від їх інтерпретації. Такий процес допомагає замінити розрізнені закладки порівнюваними даними й обговорювати креативи на конкретних прикладах.
Маршрут пошуку й параметри можна перевірити в офіційній документації jsonscraper, а опис сервісу та доступ до нього наведено на сторінці TikTok Scraper API. Почніть із кількох пошукових фраз, збережіть одну тестову відповідь і перевірте її структуру перед налаштуванням розкладу.
