Jak nie zgubić wyników wyszukiwania TikToka podczas parsowania JSON

Podczas wyszukiwania filmów w TikToku przez API filmy mogą nie znajdować się w tablicy, której jako pierwszej spodziewa się parser. W sprawdzonej odpowiedzi jsonscraper na zapytanie do endpointu `/searchVideo` pole `aweme_list` było puste, a elementy zawierające dane filmów znajdowały się w `search_item_list[].aweme_info`. Jeśli kod odczytuje tylko `aweme_list`, zapisze zero filmów, mimo że odpowiedź zawiera znalezione wyniki. Dla programisty to konkretne zadanie związane z niezawodnością: wyodrębnić obie struktury danych i znormalizować je do jednej listy przed zapisaniem w bazie lub umieszczeniem w raporcie.

Sprawdzić działający przykład i opis endpointu można w specyfikacji API jsonscraper oraz dokumentacji endpointu TikToka. Zrzut schematu w specyfikacji jest datowany na 25 października 2026 roku; pokazuje strukturę konkretnej odpowiedzi, ale nie gwarantuje obecności każdego pola w każdym kolejnym zapytaniu.

Dlaczego parser może zwrócić pustą listę

Endpoint `GET https://tiktok.evelode.com/searchVideo` wyszukuje filmy na podstawie wymaganego parametru `keyword`. Dokumentacja wymienia także `cursor`, `count`, `cache_timeout`, `date_posted`, `sort_by` i `region`. W zaobserwowanym schemacie odpowiedzi obiekt najwyższego poziomu zawiera `status` oraz zagnieżdżony obiekt `tiktok`; w nim znajdują się `cursor`, `has_more`, `status_code`, `aweme_list` i `search_item_list`.

W konkretnym zaobserwowanym przypadku zapytania ze słowem kluczowym i parametrem `count=3` tablica `aweme_list` była pusta. Jednocześnie `search_item_list` zawierała elementy, w których informacje o filmach znajdowały się w `aweme_info`. Obiekty te mogły zawierać ID filmu, podpis, URL publikacji, autora oraz statystyki, takie jak liczba wyświetleń, polubień czy komentarzy. Opisane pola odzwierciedlają zaobserwowany schemat; parser i tak powinien uwzględniać brakujące wartości.

Praktyczny wniosek jest taki, że poprawna odpowiedź HTTP i niepusta tablica w jednym oczekiwanym polu to dwie różne kontrole. Najpierw sprawdź status zewnętrzny i obecność obiektu `tiktok`, a następnie zbierz filmy ze wszystkich udokumentowanych miejsc. Na potrzeby analityki zachowuj ID i oryginalną odpowiedź: pozwoli to prześledzić, jak konkretny rekord został wyodrębniony i znormalizowany.

Normalizuj odpowiedź przed zapisaniem w magazynie danych

Wygodną granicą między API a własnym systemem jest funkcja, która przyjmuje zagnieżdżony obiekt `tiktok` i zwraca ujednolicone elementy. Powinna obsługiwać obie tablice, pomijać elementy, które nie są słownikami lub są puste, a także usuwać duplikaty tego samego filmu na podstawie `aweme_id`. Jeśli dostawca nie zwrócił liczników, pozostaw je puste: zero oznaczałoby zmierzoną wartość, podczas gdy `None` informuje o braku pola.

Poniżej znajduje się minimalny przykład dla Python 3.8+. Wykonuje jedno zapytanie, sprawdza status transportowy i status na najwyższym poziomie, normalizuje dwa warianty wyników i wypisuje wybrane pola. Klucz jest pobierany ze zmiennej środowiskowej i nie trafia do logów.

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"),
    })

Zainstaluj zależność poleceniem python -m pip install requests, ustaw `JSONSCRAPER_TIKTOK_LICENSE_KEY` w środowisku uruchomieniowym i zapisz plik, na przykład jako `search_videos.py`. Parametry zapytania odpowiadają nazwom z dokumentacji: `keyword`, `count` i `region`; `license_key` jest przekazywany jako parametr zapytania. Kod zakłada, że odpowiedź zawiera `status: "ok"`, tak jak w zapisanym przykładzie. Jeśli API zwróci inny status, przetwarzanie zostanie zatrzymane, zanim niepewna struktura zostanie przekazana dalej.

Jak przekształcić przykład w powtarzalny proces zbierania danych

Do jednorazowego eksportu wystarczy zapisać znormalizowane elementy w formacie JSON Lines lub tabeli. W działającym stale procesie dodaj zapis oryginalnej odpowiedzi wraz z czasem jej pobrania i wyszukiwanym hasłem. W osobnej tabeli znormalizowanych filmów można użyć `aweme_id` jako klucza: ponownie znaleziony wynik aktualizuje rekord, a to samo ID w dwóch tablicach nie tworzy duplikatu.

Aby pobrać następną stronę wyników, dokumentacja wskazuje parametr `cursor`: przekaż wartość otrzymaną w poprzedniej odpowiedzi. Traktuj go jak nieprzezroczysty token — przechowuj i przekazuj dalej bez przekształceń. Pętla paginacji powinna się kończyć, gdy `has_more` wskazuje brak kolejnych wyników albo API nie udostępnia użytecznego kursora; ogranicz liczbę stron w jednym uruchomieniu, aby błędna logika nie doprowadziła do nieskończonej pętli. Przytoczone źródła potwierdzają nazwę parametru oraz obecność pól `cursor` i `has_more` w zaobserwowanym schemacie, ale nie gwarantują kompletności wyników.

Jeśli monitorujesz wiele wyszukiwanych fraz, przechowuj frazę obok ID filmu i czasu zbierania danych. Dzięki temu można tworzyć zestawienia dla poszczególnych zapytań, porównywać wyniki między kolejnymi uruchomieniami i wysyłać nowe ID do kolejki dalszej klasyfikacji. Taki system opisuje pobrane wyniki wyszukiwania; jego zbiór danych zależy od zapytania, regionu, czasu i elementów faktycznie zwróconych przez API.

Sprawdzaj jakość danych, a nie tylko powodzenie zapytania

Po normalizacji warto rejestrować proste wskaźniki techniczne własnego procesu: liczbę rekordów z każdej tablicy, liczbę unikalnych ID, odsetek elementów bez ID i odsetek elementów bez statystyk. Są to miary przetwarzania konkretnej odpowiedzi, a nie oceny popularności filmów. Na przykład wzrost liczby elementów bez `play_count` oznacza, że analityka powinna zachować nieznaną wartość i oznaczyć kompletność pola, zamiast wstawiać zero.

Nie uzależniaj dalszych obliczeń od założenia, że każdy film ma taki sam zestaw statystyk. Zachowaj cały JSON w danych surowych; w tabeli analitycznej wybieraj tylko potrzebne pola i dopuszczaj wartości `NULL`. Jeśli forma odpowiedzi się zmieni, archiwum danych źródłowych pozwoli ponownie uruchomić normalizator bez wysyłania kolejnego zapytania.

Przekazuj klucz API przez sekrety CI lub zmienne środowiskowe orkiestratora. Nie umieszczaj go w URL-ach zapisywanych w logach, nie wypisuj obiektu parametrów zapytania i nie zapisuj wartości klucza razem z odpowiedziami źródłowymi. Jeśli zadanie jest uruchamiane według harmonogramu, dodaj limit czasu zapytania, obsługę błędów HTTP i ponawianie prób z przerwą; przechowuj kursor wyłącznie wraz z konkretnym zapytaniem, aby nie mieszać stron wyników z różnych wyszukiwań.

Efekt: jedna tabela zamiast pominiętych filmów

Po normalizacji kod dalszego przetwarzania otrzymuje jedną listę filmów, niezależnie od tego, czy element znalazł się w `aweme_list`, czy w `search_item_list[].aweme_info`. ID umożliwia usuwanie duplikatów, a nieobowiązkowe pola pozostają jawnie puste. Zmniejsza to ryzyko pustych raportów spowodowanych odczytywaniem tylko jednej tablicy i sprawia, że kolejny etap — eksport, filtrowanie lub klasyfikacja — jest bardziej przewidywalny.

Sprawdzanie można rozpocząć od strony TikTok Scraper API, na której podano podstawowy adres API i udostępniono przejście do wersji demonstracyjnej. Do integracji użyj oficjalnej dokumentacji i najpierw przetestuj przetwarzanie niewielkiej liczby elementów; w razie potrzeby zwiększ `count` i kontynuuj pobieranie przy użyciu kursora opisanego w dokumentacji. W efekcie otrzymasz uporządkowaną warstwę danych do własnych zadań, a nie założenie, że wyniki obejmują cały TikTok.