Michael JohnsonМаркетингова команда помічає, що в TikTok з’являються ролики про новий продукт, але щодня вручну перевіряти кілька хештегів складно. Щоб порівнювати публікації та видимі показники з часом, потрібен повторюваний збір із часовою міткою, архівом вихідних відповідей і перевіркою змін.
Для такого прототипу підійде TikTok Scraper API від jsonscraper: на сторінці продукту наведено маршрути для хештегів, користувачів, відео та пошуку. Спершу перевірте потрібний маршрут і формат відповіді в Postman, а потім перенесіть підтверджену конфігурацію в Python. Так можна побудувати повторюваний процес, отримуючи лише ті поля, які справді присутні у відповіді.
Завдання: побачити динаміку, а не окремий популярний ролик
Одна публікація з великою кількістю переглядів може привернути увагу, але для планування кампанії корисніше розуміти, скільки нових відео виявляється за темою і як змінюються публічні показники вже знайдених публікацій. Наприклад, інтернет-магазину спортивних товарів важливо оцінити потік роликів про певний вид тренувань, перш ніж готувати пов’язані з ним креативи.
Ручна перевірка ускладнює порівняння: набір результатів змінюється, показники накопичуються, а співробітники можуть записувати їх у різних форматах. Якщо зберігати знімок кожного запуску разом із часом збору та вихідним JSON, команда отримає історію власних спостережень і зможе повторно обробити дані, якщо зміниться аналітична схема.
Автоматизація складається з кількох кроків: перевірити маршрут і параметри, запитувати дані за розкладом, зберегти відповідь, підтвердити її структуру, а потім отримати потрібні поля. Отриману таблицю можна використовувати для графіків, тематичної класифікації або звіту.
Що підтверджує документація API
На сторінці TikTok Scraper API зазначено базову адресу https://tiktok.evelode.com і наведено маршрути класу Hashtag: GET /getHashtagInfo, GET /getHashtagFeed і GET /getHashtagFeedByID. На сторінці також показано приклад запиту до іншого маршруту з параметром license_key і описано налаштування ключа в колекції Postman.
Для GET /getHashtagFeed офіційна специфікація маршрутів визначає обов’язковий параметр query (URL хештегу або назва тегу), а також необов’язкові cursor, count, region і cache_timeout. У відповіді зі стрічкою очікується масив tiktok.aweme_list; серед перелічених полів елемента — aweme_id, desc, create_time, share_url, дані автора та statistics. Окремі поля можуть бути відсутні, тому перед обробкою перевіряйте фактичний JSON.
У колекції jsonscraper у Postman зручно виконати пробний запит, звірити фактичну відповідь і отримати тестовий приклад для подальшої перевірки коду. Для авторизації передається license_key; зберігайте ключ у змінній середовища й не виводьте його в журнали.
Спершу перевірте запит у Postman
Почніть з одного тестового хештегу. У колекції виберіть маршрут стрічки хештегу, задайте license_key у спосіб, зазначений у документації, і передайте назву тегу в query. За потреби додайте count і код країни в region. Виконайте запит і перевірте HTTP-статус, поле верхнього рівня status і вміст tiktok.aweme_list.
Збережіть успішну відповідь як тестовий JSON-файл. Перевірте за ним наявність ідентифікатора публікації, опису, часу публікації, посилання та статистики. Додавайте поле до аналітичної схеми лише після того, як переконаєтеся, що воно надходить у потрібному типі.
Зберігайте ключ API у змінній середовища, а не у вихідному файлі. Якщо ключ передається в URL, маскуйте його під час журналювання запиту, щоб повна адреса не потрапляла до журналів.
Клієнт Python для запиту й архівації
Наведені нижче маршрут та назви параметрів відповідають опублікованій специфікації: для хештегу використовується query, а авторизація передається через license_key. Приклад сумісний із Python 3.8+ і зберігає вихідну відповідь разом із метаданими запуску.
import json
import os
from datetime import datetime, timezone
from pathlib import Path
import requests
BASE_URL = "https://tiktok.evelode.com"
API_KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
def fetch_hashtag_feed(hashtag: str) -> dict:
params = {
"license_key": API_KEY,
"query": hashtag,
"count": 20,
}
response = requests.get(
f"{BASE_URL}/getHashtagFeed",
params=params,
timeout=45,
)
response.raise_for_status()
payload = response.json()
if payload.get("status") != "ok":
raise RuntimeError("API повернув статус, відмінний від ok")
return payload
def archive_response(hashtag: str, payload: dict) -> Path:
collected_at = datetime.now(timezone.utc).isoformat()
safe_tag = hashtag.lstrip("#").replace("/", "_")
output_dir = Path("data/raw") / safe_tag
output_dir.mkdir(parents=True, exist_ok=True)
filename = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ.json")
file_path = output_dir / filename
file_path.write_text(
json.dumps(
{
"hashtag": hashtag,
"collected_at": collected_at,
"response": payload,
},
ensure_ascii=False,
indent=2,
),
encoding="utf-8",
)
return file_path
if __name__ == "__main__":
tag = "#примертеми"
payload = fetch_hashtag_feed(tag)
saved_path = archive_response(tag, payload)
print(f"Архів збережено: {saved_path}")
Перед запуском задайте змінну середовища JSONSCRAPER_TIKTOK_LICENSE_KEY. Запит використовує підтверджений query і обмежує кількість запитаних елементів за допомогою count. У відповіді перевіряються зовнішній статус і статус JSON; архів зберігає фактичні дані для подальшої обробки. Перевірте запуск на одному хештегу, перш ніж додавати розклад і аналітику.
Як додати нормалізацію без крихких припущень
У відповіді зі стрічкою документація вказує масив tiktok.aweme_list. Перед перетворенням перевірте, що tiktok — об’єкт, а aweme_list — список. Для кожного елемента отримуйте лише підтверджені поля, наприклад aweme_id, desc, create_time, share_url і значення з statistics, якщо вони присутні.
Внутрішня таблиця може містити хештег запиту, час збору, ідентифікатор відео та вибрані метрики. Для необов’язкового або відсутнього показника зберігайте порожнє значення: відсутність метрики відрізняється від виміряного нуля. Зберігайте вихідні відповіді окремо, щоб повторно побудувати таблицю без нового запиту.
Якщо формат відповіді зміниться, перевірка типів має зупинити некоректну обробку та створити діагностичне повідомлення. Збережіть тестовий JSON поруч із тестом парсера: він допоможе перевірити, чи продовжує нова версія коду обробляти відому схему.
Метрики на основі повторних спостережень
Якщо відповідь містить лічильники, зберігайте кожне спостереження з часовою міткою. Для однієї публікації порівняйте значення під час двох запусків і обчисліть спостережувану зміну за інтервал. Для зіставлення використовуйте aweme_id, зазначений у специфікації, і перевіряйте його наявність у кожному елементі.
Кількість уперше виявлених публікацій за день можна підраховувати за результатами ваших запусків. Ця метрика описує потік, повернутий конкретними запитами з заданими параметрами та розкладом. Вона дає змогу порівнювати власні знімки, якщо метод збору залишається послідовним.
Мінімальний звіт може показувати кількість нових виявлених публікацій за днями, розподіл доступних лічильників і зміну значень у повторно знайдених відео. Додайте час запиту й назву вихідного файла, щоб аналітик міг перевірити походження кожного запису.
Розклад і обробка помилок
Коли запит і розбір перевірено, запускайте скрипт за розкладом — наприклад, через cron, GitHub Actions або оркестратор даних. Винесіть список хештегів в окрему конфігурацію, щоб додавати й видаляти теми без зміни логіки клієнта.
Для автоматичного запуску задайте тайм-аут, обмежену кількість повторів у разі тимчасових мережевих помилок і журналювання HTTP-статусу та тривалості запиту. Не записуйте ключ у журнал. У разі помилки розбору зберігайте безпечні діагностичні відомості й сповіщайте відповідального співробітника.
Специфікація підтримує пагінацію параметром cursor для стрічки хештегу. Якщо вона потрібна, зберігайте курсор із відповіді та передавайте його в наступному запиті без перетворення; обробляйте лише повернуті результати й контролюйте has_more, якщо це поле присутнє. Якщо запити за кількома хештегами повертають одну публікацію, виберіть ключ дедуплікації відповідно до завдання: враховувати публікацію окремо для кожного хештегу чи рахувати лише унікальні відео.
Класифікація й автоматизація звітів
Після отримання перевірених рядків можна додати класифікацію описів відео за заданими темами: поле desc зазначене в схемі елемента. Модель може групувати публікації за форматом — наприклад, інструкції, огляди чи досвід користувачів. Зберігайте вихідний текст, мітку, версію інструкції та результат, а сумнівні випадки передавайте людині на перевірку.
Числові показники обчислюйте звичайним кодом, щоб повторні запуски давали відтворювану арифметику. Класифікатор корисний для обробки тексту; підсумковий звіт має пов’язувати висновки з конкретними рядками й датами спостережень.
У сценарії без коду ті самі етапи можна поєднати в автоматизаторі: розклад, HTTP-запит за перевіреною конфігурацією, перевірка відповіді, збереження JSON, перетворення підтверджених полів і сповіщення про помилку. Спершу перевірте контракт у Postman, а потім переносьте його в Python, n8n або Make.
Очікуваний результат і наступний крок
Після налаштування команда матиме архів відповідей API й таблицю спостережень за вибраними хештегами. Вони допоможуть знаходити нові публікації, порівнювати доступні показники з часом і вибирати матеріали для змістовного аналізу. Для зіставних результатів дотримуйтеся єдиного розкладу, параметрів запитів і правил нормалізації.
Почніть з одного маршруту й однієї реальної відповіді: виконайте запит /getHashtagFeed із параметром query, збережіть JSON, а потім додавайте розбір полів і розклад. На сторінці TikTok Scraper API наведено базову адресу й карту маршрутів, а специфікація маршрутів містить назви параметрів для реалізації клієнта.