Michael JohnsonПісля запуску кампанії команді може бути корисно перевірити, які публічні відео з’являються в результатах пошуку за вибраними словами. Ручний пошук важко повторити й порівняти через кілька днів. Невеликий збирач може запускати однакові запити за розкладом і архівувати відповіді з датою та пошуковою фразою, щоб аналітик міг перевірити записи й підготувати власне зведення.
У цьому посібнику показано архівний конвеєр на Python для збереження результатів пошуку за фіксованими фразами. На відміну від моніторингу окремих хештегів або облікових записів, ключем до порівняння тут є повторення тих самих пошукових фраз і збереження окремого знімка кожної відповіді. На сторінці TikTok Scraper API від jsonscraper зазначено базову адресу й маршрут GET /searchVideo; у документації цього маршруту пошукова фраза передається в обов’язковому параметрі keyword.
Завдання та межі вимірювання
Уявімо, що маркетолог хоче щодня збирати результати пошуку за кількома фіксованими фразами: назвою продукту, категорією та формулюванням проблеми клієнта. Для кожного запиту система зберігає час збору й відповідь API. Після перевірки прикладу відповіді можна додати нормалізацію полів, які справді є в JSON, наприклад ідентифікатора відео або публічних лічильників, якщо вони там наявні.
Архів відповідає на конкретне запитання: які записи повернув пошук за збереженою фразою під час цього запуску? Якщо відповідь містить метрики, повторні спостереження можуть показати різницю між значеннями, зафіксованими в різні моменти. Така різниця стосується спостережуваних знімків і проміжку між ними; для порівняння зберігайте обидва часи збору й те саме поле.
Зберігайте запит разом із відповіддю. Склад результатів залежить від конкретної пошукової фрази й часу збору. Тому архів корисний для відстеження результатів за вибраними запитами, а не як повний огляд усього контенту TikTok. Ідентифікатори, вихідні відповіді й часові позначки допомагають перевірити, звідки взявся кожен рядок у подальшій таблиці.
Перевірте маршрут і його параметри
У переліку маршрутів TikTok API зазначено базову адресу https://tiktok.evelode.com і GET /searchVideo. В актуальній специфікації API keyword визначено як обов’язковий параметр пошуку; серед необов’язкових параметрів перелічено cursor, count, cache_timeout, date_posted, sort_by і region. Для авторизації передається license_key. Відомості про маршрут також доступні в документації Python SDK.
Параметри count і date_posted допомагають задати розмір відповіді й часовий фільтр; sort_by приймає документовані значення most-liked, relevance або date-posted. Якщо використовуєте пагінацію, передавайте отриманий у попередній відповіді cursor як непрозоре значення, не обчислюючи його самостійно. Для порівнюваного щоденного архіву зберігайте параметри запиту й версію власного коду разом із даними.
У прикладі нижче використано невелике значення count для тестового запуску й фіксований регіон US. Перед щоденним збором перевірте один запит, його HTTP-статус і структуру JSON. Схема відповіді може містити знайдені відео в tiktok.aweme_list або tiktok.search_item_list, де об’єкт відео розміщений у aweme_info; код підтримує обидві форми, які спостерігалися.
Підготуйте проєкт
Створіть віртуальне середовище й установіть requests:
python -m venv .venv
source .venv/bin/activate
pip install requestsУ PowerShell середовище активується командою .venv\Scripts\Activate.ps1. Задайте ключ і список пошукових фраз через змінні середовища. Для TikTok API використовуйте документовану назву змінної JSONSCRAPER_TIKTOK_LICENSE_KEY:
export JSONSCRAPER_TIKTOK_LICENSE_KEY="ваш_ключ"
export TIKTOK_QUERIES="назва продукту,категорія товару,проблема клієнта"Збір і збереження знімків
Приклад надсилає по одному запиту для кожної фрази до документованого маршруту, а потім зберігає вихідний JSON, час збору й використані параметри. У назві файлу зазначено дату й пошукову фразу. Ключ зберігається в середовищі й не потрапляє до архіву.
import json
import os
import re
import time
from datetime import datetime, timezone
from pathlib import Path
import requests
BASE_URL = "https://tiktok.evelode.com"
ENDPOINT = "/searchVideo"
LICENSE_KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
QUERIES = [
item.strip()
for item in os.environ["TIKTOK_QUERIES"].split(",")
if item.strip()
]
OUT = Path("data")
OUT.mkdir(exist_ok=True)
def safe_name(text):
cleaned = re.sub(r"[^a-zA-Z0-9_-]+", "_", text).strip("_")
return cleaned[:80] or "query"
def fetch(query):
params = {
"license_key": LICENSE_KEY,
"keyword": query,
"count": 10,
"region": "US",
}
response = requests.get(
BASE_URL + ENDPOINT,
params=params,
timeout=60,
)
response.raise_for_status()
payload = response.json()
if payload.get("status") != "ok":
raise RuntimeError("API повернув статус, відмінний від ok")
return payload
def extract_videos(payload):
tiktok = payload.get("tiktok") or {}
videos = list(tiktok.get("aweme_list") or [])
for item in tiktok.get("search_item_list") or []:
video = item.get("aweme_info") or {}
if video:
videos.append(video)
return videos
for query in QUERIES:
collected_at = datetime.now(timezone.utc).isoformat()
payload = fetch(query)
record = {
"collected_at": collected_at,
"query": query,
"request": {
"endpoint": ENDPOINT,
"keyword": query,
"count": 10,
"region": "US",
},
"videos_found": len(extract_videos(payload)),
"payload": payload,
}
filename = OUT / f"{collected_at[:10]}_{safe_name(query)}.json"
filename.write_text(
json.dumps(record, ensure_ascii=False, indent=2),
encoding="utf-8",
)
print(f"Збережено відповідь для запиту: {query}")
time.sleep(1)
print(f"Збережено відповідей: {len(QUERIES)}")Цей мінімальний збирач виконує один запит на фразу з count=10. Для ширшого збору додайте пагінацію за допомогою cursor: виконуйте наступні запити, передаючи значення курсора з відповіді, доки API вказує на наявність наступних результатів, і зберігайте кожну відповідь окремо. Курсор і кількість результатів визначають конкретний прохід; збережений JSON дає змогу згодом перевірити, що саме повернув кожен запит.
Приклад перевіряє зовнішній status, а потім читає об’єкт tiktok. Він збирає елементи з aweme_list, а також із search_item_list[].aweme_info, якщо така форма присутня. Можливі поля відеозапису включають ідентифікатор, опис, автора, посилання й статистику; окремі поля можуть бути відсутні. Тому зберігайте повну відповідь, а під час нормалізації перевіряйте наявність кожного поля.
Інтервал в одну секунду — це пауза між запитами самого скрипту, а не твердження про ліміти сервісу. Налаштуйте частоту й повторні спроби з урахуванням умов доступу та документації. Параметр cache_timeout документовано для пошуку; він дає змогу задати строк кешування в секундах, а згідно зі специфікацією значення 0 вимикає кешування. Додавайте його до запиту, коли така поведінка відповідає вашому сценарію.
Додайте нормалізацію на основі фактичної відповіді
Після першого запуску відкрийте збережений файл і вивчіть структуру payload. Функція extract_videos у прикладі збирає елементи з двох місць, документованих для форм пошукової відповіді. Знайдіть точні ключі потрібних для аналізу полів. Якщо поле відсутнє в конкретному записі, зберігайте його як відсутнє значення, а не підставляйте число навмання.
Для подальшої обробки зручно сформувати один рядок для кожного знайденого об’єкта, додавши до нього collected_at і query. Перевірені поля можна зберігати в CSV або базі даних, а вихідний JSON залишити в архіві. Така пара дає змогу будувати зручні таблиці й водночас перевіряти походження кожного запису.
Якщо API повертає ідентифікатор відео, використовуйте його, щоб пов’язувати спостереження того самого відео в різних запусках. Зберігайте кожне спостереження окремо, не перезаписуючи попередні. Якщо стабільного ідентифікатора немає, спочатку перевірте, які атрибути дають змогу зіставляти записи, і не вважайте збіг тексту опису надійною гарантією.
Порівняйте знімки й підготуйте звіт
Після нормалізації згрупуйте записи за перевіреним ідентифікатором і відсортуйте за часом збору. Різницю між двома послідовними значеннями лічильників можна обчислити звичайним кодом. Наприклад, перехід від 12 400 до 18 900 означає, що між цими знімками значення лічильника змінилося на 6 500. У звіті зазначте дати спостережень і вихідне поле, щоб читач міг перевірити розрахунок.
До корисної структури підсумкової таблиці входять пошукова фраза, ідентифікатор публікації, час збору й вибрані поля з відповіді. Зведення можна згрупувати за запитами й відсортувати за одним підтвердженим лічильником. Це дасть команді список повернутих записів, який можна перевірити й переглянути далі; таблицю або повідомлення реалізуйте окремим кроком після вивчення фактичної схеми.
Спочатку зберігайте файли JSON локально. Коли збір стане регулярним, перенесіть нормалізовані рядки до PostgreSQL або аналітичного сховища, а вихідні відповіді — до об’єктного сховища, додаючи дату й запит до назви. Збереження оригіналу особливо корисне під час удосконалення парсера: його можна повторно запустити на історичних даних, не звертаючись до API знову.
Запускайте збір за розкладом
Для щоденного архіву викликайте скрипт через cron або інший планувальник, доступний у вашому середовищі. Наприклад, завдання може запускати файл Python раз на добу, передаючи ключ і пошукові фрази через змінні середовища. Перед регулярним використанням перевірте один запит, потім увесь список і лише після цього підключайте розклад.
Для надійного запуску зберігайте статус кожного запиту, обмежуйте кількість повторних спроб у разі тимчасових помилок і позначайте збір як неповний, якщо запит за однією з фраз завершився невдало. Не додавайте ключ до повідомлень про помилки. Також корисно розділяти файли за датою й назвою запиту, щоб повторний запуск не перезаписував попередній знімок.
Обирайте частоту відповідно до завдання й обсягу запитів. Для щоденного огляду достатньо одного запуску на день; частіший збір має сенс, коли команді важливі зміни протягом дня. Почніть із невеликого списку фраз, перевірте корисність повернених результатів і потім розширюйте збір у межах умов доступу та правил використання даних.
Використовуйте ШІ для тематичного групування
Після підтвердження схеми відповіді вибрані текстові поля можна передавати моделі для групування описів за заздалегідь визначеними темами або підготовки короткої чернетки зведення. Зберігайте поруч із класифікацією вихідний ідентифікатор публікації, пошукову фразу й фрагмент тексту, на якому ґрунтується категорія. Так аналітик зможе перейти від висновку моделі до вихідного запису.
Числові різниці, сортування й дедуплікацію обчислюйте звичайним кодом. Модель придатна для обробки тексту й формулювання звіту, а лічильники та часові позначки беріть зі збережених відповідей. Розділення цих операцій робить походження кожного висновку зрозумілим.
Перевіряйте вручну частину автоматичних категорій і зберігайте виправлення як тестові приклади. Якщо різні типи публікацій регулярно потрапляють до однієї групи, уточніть визначення категорій і повторіть перевірку. Такий процес допомагає оцінити якість класифікації на даних вашого завдання.
Підсумок: відтворюваний архів і перевірюване зведення
Після виконання документованого запиту з параметром keyword команда матиме архів: які фрази запускалися, коли це відбувалося та які дані API повернуло для кожної з них. На його основі можна побудувати таблицю результатів, порівняти підтверджені поля між знімками й підготувати список знайдених публікацій для ручного аналізу.
Почніть з одного тестового запиту, потім налаштуйте список фраз і розклад. В описі TikTok Scraper API наведено базову адресу й перелік маршрутів; параметри /searchVideo і форму відповіді описано в специфікації API. Архівування перевірених відповідей створює основу для відтворюваної аналітики за фіксованими пошуковими фразами.