Як не втратити результати пошуку TikTok під час обробки JSON

Під час пошуку відео в TikTok через API ролики можуть міститися не в тому масиві, якого насамперед очікує обробник. У перевіреній відповіді jsonscraper на запит `/searchVideo` поле `aweme_list` було порожнім, а елементи з даними відео містилися в `search_item_list[].aweme_info`. Якщо код читає лише `aweme_list`, він збереже нуль роликів, хоча відповідь містить знайдені відео. Для розробника це конкретне завдання з надійності: витягти обидві форми даних і нормалізувати їх в єдиний список перед записом у базу чи передаванням у звіт.

Перевірити приклад і опис маршруту можна в специфікації API jsonscraper та документації endpoint TikTok. Знімок схеми у специфікації датовано 25 жовтня 2026 року; він демонструє структуру конкретної відповіді, а не гарантує наявність кожного поля в усіх наступних запитах.

Чому парсер може повертати порожній список

Маршрут `GET https://tiktok.evelode.com/searchVideo` шукає відео за обов’язковим параметром `keyword`. У документації також зазначено `cursor`, `count`, `cache_timeout`, `date_posted`, `sort_by` і `region`. У схемі спостереженої відповіді зовнішній об’єкт містить `status` і вкладений об’єкт `tiktok`; усередині нього — `cursor`, `has_more`, `status_code`, `aweme_list` і `search_item_list`.

У конкретному спостереженні для запиту з ключовим словом і `count=3` масив `aweme_list` виявився порожнім. Водночас `search_item_list` містив елементи, у яких відомості про відео були в `aweme_info`. Ці об’єкти могли містити ID відео, підпис, URL публікації, автора та статистику, наприклад кількість переглядів, вподобань або коментарів. Описані поля відповідають спостереженій схемі; обробник усе одно має коректно працювати за відсутності значень.

Практичний висновок такий: успішний HTTP-запит і непорожній масив в одному очікуваному полі — це різні перевірки. Спочатку перевірте зовнішній статус і наявність `tiktok`, а потім зберіть ролики з кожного задокументованого місця. Для аналітики зберігайте ID та вихідну відповідь: так можна відстежити, як саме запис було отримано й нормалізовано.

Нормалізуйте відповідь перед записом у сховище

Зручна межа між API і власною системою — функція, яка приймає вкладений об’єкт `tiktok` і повертає уніфіковані елементи. Вона має обробляти обидва масиви, пропускати елементи, що не є словниками, або порожні елементи, а також усувати повтори одного ролика за `aweme_id`. Лічильники залишайте порожніми, якщо провайдер їх не повернув: нуль означав би виміряне значення, тоді як `None` повідомляє про відсутність поля.

Нижче наведено мінімальний приклад для Python 3.8+. Він виконує один запит, перевіряє транспортний статус і статус верхнього рівня, нормалізує два варіанти результату та виводить вибрані поля. Ключ зчитується зі змінної середовища й не потрапляє до журналу.

import os
import requests

BASE_URL = "https://tiktok.evelode.com"


def extract_videos(tiktok):
    candidates = []
    aweme_list = tiktok.get("aweme_list") or []
    if isinstance(aweme_list, list):
        candidates.extend(aweme_list)

    search_items = tiktok.get("search_item_list") or []
    if isinstance(search_items, list):
        for item in search_items:
            if isinstance(item, dict):
                candidates.append(item.get("aweme_info"))

    unique = {}
    for video in candidates:
        if not isinstance(video, dict):
            continue
        video_id = video.get("aweme_id")
        if video_id:
            unique[video_id] = video
    return list(unique.values())


license_key = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
response = requests.get(
    BASE_URL + "/searchVideo",
    params={
        "license_key": license_key,
        "keyword": "python tutorial",
        "count": 10,
        "region": "US",
    },
    timeout=30,
)
response.raise_for_status()
payload = response.json()

if payload.get("status") != "ok":
    raise RuntimeError("TikTok API returned a non-ok status")

tiktok = payload.get("tiktok")
if not isinstance(tiktok, dict):
    raise RuntimeError("Response has no tiktok object")

for video in extract_videos(tiktok):
    stats = video.get("statistics") or {}
    author = video.get("author") or {}
    print({
        "aweme_id": video.get("aweme_id"),
        "desc": video.get("desc"),
        "share_url": video.get("share_url"),
        "author": author.get("unique_id"),
        "play_count": stats.get("play_count"),
        "digg_count": stats.get("digg_count"),
        "comment_count": stats.get("comment_count"),
    })

Установіть залежність командою python -m pip install requests, задайте `JSONSCRAPER_TIKTOK_LICENSE_KEY` у середовищі виконання та збережіть файл, наприклад, як `search_videos.py`. Параметри запиту відповідають задокументованим назвам: `keyword`, `count` і `region`; `license_key` передається як параметр запиту. Код передбачає, що відповідь містить `status: "ok"`, як у зафіксованому прикладі. Якщо API поверне інший статус, обробка зупиниться, перш ніж сумнівна структура буде передана далі.

Як перетворити приклад на повторюваний збір даних

Для разового експорту достатньо записати нормалізовані елементи у JSON Lines або таблицю. Для постійного процесу додайте збереження вихідної відповіді разом із часом отримання та пошуковим запитом. В окремій таблиці нормалізованих роликів можна використовувати `aweme_id` як ключ: повторний результат оновлюватиме запис, а повтор одного ID у двох масивах не створюватиме дублікат.

Для запиту наступної сторінки документація вказує параметр `cursor`: передавайте значення, отримане в попередній відповіді. Вважайте його непрозорим токеном — зберігайте й передавайте назад без змін. Цикл пагінації має завершуватися, якщо продовження немає за ознакою `has_more` або API не надає придатного курсора; обмежте кількість сторінок за один запуск, щоб помилкова логіка не спричинила нескінченний цикл. Зафіксовані джерела підтверджують назву параметра та наявність полів `cursor` і `has_more` у спостереженій схемі, але не гарантують повноти результатів.

Для моніторингу кількох пошукових фраз зберігайте фразу поруч з ID ролика та часом збору даних. Тоді можна створювати зрізи за запитами, порівнювати результати між запусками й надсилати нові ID у чергу для подальшої класифікації. Така система описує отримані результати пошуку; її набір даних залежить від запиту, регіону, часу та фактично повернутих елементів API.

Перевіряйте якість даних, а не лише успішність запиту

Після нормалізації корисно вести прості технічні показники свого конвеєра: кількість записів із кожного масиву, кількість унікальних ID, частку елементів без ID і частку елементів без статистики. Це метрики обробки конкретної відповіді, а не оцінки популярності відео. Наприклад, збільшення кількості елементів без `play_count` означає, що аналітика має зберігати невідоме значення й позначати повноту поля, а не підставляти нуль.

Не прив’язуйте подальші обчислення до припущення, що кожне відео обов’язково має однаковий набір статистики. Для збереження сирих даних залиште весь JSON; для аналітичної таблиці вибирайте лише потрібні поля й допускайте `NULL`. Якщо форма відповіді зміниться, вихідний архів дасть змогу повторно запустити нормалізатор без нового запиту.

Передавайте ключ API через секрети CI або змінні середовища оркестратора. Не додавайте його до URL, які зберігаються в журналах, не виводьте об’єкт параметрів запиту й не зберігайте значення ключа поруч із вихідними відповідями. Якщо процес запускається за розкладом, додайте обмеження часу запиту, обробку HTTP-помилок і повторні спроби з паузою; зберігайте курсор лише разом із конкретним пошуковим запитом, щоб не змішувати сторінки різних результатів пошуку.

Результат: єдина таблиця замість пропущених роликів

Після нормалізації наступний код отримує один список відео незалежно від того, чи надійшов елемент у `aweme_list`, чи в `search_item_list[].aweme_info`. За ID можна усунути повтори, а необов’язкові поля залишаються явно порожніми. Це знижує ризик порожніх звітів через читання лише одного масиву та робить наступний етап — експорт, фільтрування чи класифікацію — передбачуваним.

Почати перевірку можна зі сторінки TikTok Scraper API, де вказано базову адресу API та доступний перехід до демоверсії. Для інтеграції використовуйте офіційну документацію та спочатку перевірте обробку на невеликій кількості елементів; за потреби збільшуйте `count` і продовжуйте видачу за задокументованим курсором. У результаті ви отримаєте акуратний шар даних для своїх завдань, а не припущення про повне охоплення TikTok.