Michael JohnsonHTTP 200 не гарантує, що щоденний моніторинг TikTok зібрав відео. Результати пошуку можуть міститися в aweme_list або в search_item_list[].aweme_info; скрипт, який читає лише перший масив, може завершитися без помилки й записати порожній звіт. Надійна перевірка окремо підтверджує транспортний і прикладний статуси, витягує обидва підтримувані варіанти структури та фіксує, скільки унікальних відео вдалося отримати під час цього запуску.
Що саме варто діагностувати
Уявімо завдання: щоранку команда збирає публічні відео за кількома запитами, щоб помічати нові публікації про продукт. Важливий результат такого процесу — відтворюваний список знайдених записів з описом, автором, датою публікації та доступними показниками. Якщо звіт раптом порожній, причина може бути в обробці JSON, зміні набору результатів, повторній видачі вже відомих відео або справжньому збої запиту. Одне число — наприклад, довжина aweme_list — не допоможе розрізнити ці випадки.
У jsonscraper TikTok Scraper API маршрут пошуку /searchVideo приймає обов’язковий параметр keyword і додаткові параметри count, cursor, date_posted, sort_by та region. Документація маршруту описує пагінацію через cursor; його слід передавати як непрозоре значення з попередньої відповіді. Параметр count задає бажану кількість результатів, а не гарантує повне охоплення публікацій.
Розділіть перевірку на чотири сигнали
Корисна діагностика складається з чотирьох незалежних перевірок. Перша — HTTP-запит завершився успішно. Друга — зовнішній status відповіді дорівнює ok, а внутрішній tiktok.status_code відповідає успішній відповіді. Третя — об’єкт tiktok присутній, а записи витягуються з обох задокументованих місць відповіді. Четверта — після усунення дублікатів залишилися записи з ідентифікаторами, придатними для збереження. У журналі зберігайте кількість витягнутих елементів до та після усунення дублікатів: різниця показує, чи виникли повтори на етапі нормалізації.
Відсутнє поле потрібно залишати порожнім, а не замінювати вигаданим значенням. Наприклад, лічильник переглядів може бути відсутнім у конкретному записі. Збереження вихідного JSON поруч із нормалізованим рядком допоможе згодом перевірити, чи втратилася інформація під час розбору, чи її не було у вихідній відповіді.
Мінімальний запит і нормалізація на Python
Специфікація jsonscraper визначає базову адресу https://tiktok.evelode.com і передавання ключа в параметрі запиту license_key. Наведений нижче приклад використовує задокументовані параметри; ключ зчитується зі змінної середовища й не виводиться в журнал. Установіть залежність командою python -m pip install requests, а потім задайте JSONSCRAPER_TIKTOK_LICENSE_KEY у середовищі.
import json
import os
from datetime import datetime, timezone
from pathlib import Path
import requests
BASE_URL = "https://tiktok.evelode.com/searchVideo"
KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
def extract_videos(payload):
"""Зібрати відео з обох відомих структур відповіді пошуку."""
tiktok = payload.get("tiktok") or {}
videos = []
for item in tiktok.get("aweme_list") or []:
if isinstance(item, dict):
videos.append(item)
for item in tiktok.get("search_item_list") or []:
if isinstance(item, dict):
aweme = item.get("aweme_info")
if isinstance(aweme, dict):
videos.append(aweme)
return videos
def main():
params = {
"license_key": KEY,
"keyword": "приклад запиту про продукт",
"count": 20,
"region": "US",
}
response = requests.get(BASE_URL, params=params, timeout=30)
response.raise_for_status()
payload = response.json()
if payload.get("status") != "ok":
raise RuntimeError("API повернув зовнішній статус, відмінний від ok")
tiktok = payload.get("tiktok")
if not isinstance(tiktok, dict):
raise RuntimeError("У відповіді відсутній об’єкт tiktok")
if tiktok.get("status_code") != 0:
raise RuntimeError("Внутрішній status_code не дорівнює успішному значенню 0")
raw_videos = extract_videos(payload)
unique = {}
for video in raw_videos:
video_id = video.get("aweme_id")
if video_id:
unique.setdefault(str(video_id), video)
snapshot = {
"collected_at": datetime.now(timezone.utc).isoformat(),
"keyword": params["keyword"],
"status": payload.get("status"),
"status_code": tiktok.get("status_code"),
"raw_items": len(raw_videos),
"unique_items": len(unique),
"has_more": tiktok.get("has_more"),
"cursor": tiktok.get("cursor"),
"videos": list(unique.values()),
}
Path("snapshots").mkdir(exist_ok=True)
stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
Path(f"snapshots/{stamp}.json").write_text(
json.dumps(snapshot, ensure_ascii=False, indent=2),
encoding="utf-8",
)
print({
"status": snapshot["status"],
"status_code": snapshot["status_code"],
"raw_items": snapshot["raw_items"],
"unique_items": snapshot["unique_items"],
"has_more": snapshot["has_more"],
})
if __name__ == "__main__":
main()Скрипт перевіряє транспортний рівень через raise_for_status(), потім перевіряє зовнішній статус, наявність об’єкта tiktok і внутрішній status_code. Після цього він витягує записи з двох структур пошуку, усуває дублікати за aweme_id і зберігає знімок із часом збору. Якщо відповідних записів немає, файл усе одно містить відомості про запуск, що дає змогу відрізнити збережений порожній результат від відсутнього звіту.
Як перетворити знімки на сигнал для команди
Запускайте скрипт за розкладом за допомогою cron, CI або планувальника робочого процесу. Для кожного запиту зберігайте окремі знімки або додавайте ключове слово до імені файлу. У таблиці стану достатньо записувати час запуску, статус, кількість витягнутих і унікальних записів, а також прапорець has_more. Сповіщення корисно надсилати в разі помилки запиту, відсутності обов’язкових частин відповіді або різкої зміни кількості витягнутих записів порівняно з власною історією.
Таке порівняння виявляє аномалію пайплайна, але саме по собі не пояснює її причину. Менша кількість результатів може відображати склад поточної видачі, а не несправність API чи парсера. Тому корисно зберігати вихідний JSON, порівнювати однакові параметри та перевіряти знайдені ідентифікатори. Поріг сповіщення обирайте на основі спостережень саме за вашим запитом, а не універсального числа.
Для пагінації використовуйте cursor з відповіді й завершуйте обхід, коли API повідомляє про відсутність наступних результатів. Зберігайте використані курсори та параметри запиту, щоб запуск можна було відтворити. Параметри date_posted і sort_by дають змогу задавати часовий фільтр і сортування; якщо завдання вимагає відтворюваних порівнянь, фіксуйте їх між запусками.
Як читати результат
Після впровадження команда отримує перевірювану відповідь на три практичні запитання: чи відбувся запит, де в JSON містяться результати і скільки унікальних відео потрапило до збереженого знімка. Це скорочує шлях від порожньої таблиці до діагностики: спочатку перевіряються статуси й структура, потім — параметри, повтори та вміст вихідної відповіді.
Схема відповіді та доступні поля можуть відрізнятися між записами. Під час live-перевірки jsonscraper від 25 жовтня 2026 року пошук повертав поля ідентифікатора, опису, автора та статистики; значення для конкретного запису слід вважати необов’язковими. Робочий звіт зберігає фактично отримані дані й не підміняє пропуски нулями.
Почати можна зі сторінки TikTok Scraper API, а точні маршрути й параметри звірити в офіційній документації API. Така перевірка корисна перед запуском моніторингу: звіт стає спостережуваним результатом, якість якого можна діагностувати.
