Jak při parsování JSON nepřijít o výsledky vyhledávání na TikToku

Při vyhledávání videí na TikToku přes API se mohou videa nacházet v jiném poli, než jaké zpracovatel očekává jako první. V ověřené odpovědi jsonscraperu na požadavek `/searchVideo` bylo pole `aweme_list` prázdné, zatímco prvky s údaji o videích se nacházely v `search_item_list[].aweme_info`. Pokud kód čte pouze `aweme_list`, uloží nula videí, přestože odpověď nalezená videa obsahuje. Pro vývojáře je to konkrétní úkol v oblasti spolehlivosti: extrahovat obě podoby dat a před uložením do databáze nebo odesláním do reportu je normalizovat do jediného seznamu.

Ověřit živý příklad a popis trasy lze v specifikaci API jsonscraperu a dokumentaci endpointu TikToku. Snímek schématu ve specifikaci je datován 25. října 2026; ukazuje strukturu konkrétní odpovědi, ale nezaručuje přítomnost každého pole v každém následujícím požadavku.

Proč může parser vrátit prázdný seznam

Trasa `GET https://tiktok.evelode.com/searchVideo` vyhledává videa podle povinného parametru `keyword`. Dokumentace uvádí také `cursor`, `count`, `cache_timeout`, `date_posted`, `sort_by` a `region`. Ve schématu pozorované odpovědi obsahuje nejvyšší objekt `status` a vnořený objekt `tiktok`; ten obsahuje `cursor`, `has_more`, `status_code`, `aweme_list` a `search_item_list`.

Při konkrétním pozorování požadavku s klíčovým slovem a `count=3` bylo pole `aweme_list` prázdné. `search_item_list` přitom obsahoval prvky, jejichž údaje o videu byly v `aweme_info`. Tyto objekty mohly obsahovat ID videa, popisek, URL příspěvku, autora a statistiky, například počet zhlédnutí, lajků nebo komentářů. Uvedená pole odpovídají pozorovanému schématu; zpracovatel by přesto měl počítat s chybějícími hodnotami.

Praktický závěr je, že úspěšný požadavek HTTP a neprázdné pole v jednom očekávaném místě jsou dvě různé kontroly. Nejprve ověřte vnější stav a přítomnost `tiktok`, potom shromážděte videa ze všech zdokumentovaných míst. Pro analytiku ukládejte ID i původní odpověď: můžete tak dohledat, jak byl konkrétní záznam extrahován a normalizován.

Normalizujte odpověď před uložením do úložiště

Vhodným rozhraním mezi API a vlastním systémem je funkce, která přijme vnořený objekt `tiktok` a vrátí sjednocené položky. Měla by zpracovat obě pole, přeskočit prvky, které nejsou slovníky, i prázdné prvky a také odstranit duplicity videa podle `aweme_id`. Pokud poskytovatel počítadla nevrátil, ponechte je prázdná: nula by znamenala naměřenou hodnotu, zatímco `None` vyjadřuje, že pole chybí.

Níže je minimální příklad pro Python 3.8+. Provede jeden požadavek, ověří stav přenosu i stav na nejvyšší úrovni, normalizuje dvě varianty výsledků a vypíše vybraná pole. Klíč se načítá z proměnné prostředí a nezapisuje se do logu.

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

Nainstalujte závislost příkazem python -m pip install requests, nastavte `JSONSCRAPER_TIKTOK_LICENSE_KEY` v prostředí, ve kterém se program spouští, a uložte soubor například jako `search_videos.py`. Parametry požadavku odpovídají názvům v dokumentaci: `keyword`, `count` a `region`; `license_key` se předává jako parametr URL dotazu. Kód předpokládá, že odpověď obsahuje `status: "ok"`, stejně jako v zaznamenaném příkladu. Pokud API vrátí jiný stav, zpracování se zastaví dřív, než se předá dál pochybná struktura.

Jak z příkladu vytvořit opakovatelný sběr

Pro jednorázový export stačí zapisovat normalizované položky do JSON Lines nebo tabulky. V trvalém procesu ukládejte také původní odpověď spolu s časem získání a vyhledávacím dotazem. Tabulka normalizovaných videí může jako klíč používat `aweme_id`: při opakovaném výsledku se záznam aktualizuje a opakované ID ve dvou polích nevytvoří duplicitu.

Pro vyžádání další stránky dokumentace uvádí parametr `cursor`: předejte hodnotu získanou v předchozí odpovědi. Považujte ji za neprůhledný token — uložte ji a vraťte bez úprav. Cyklus stránkování ukončete, když `has_more` signalizuje, že už nic dalšího není, nebo když API neposkytne použitelný kurzor; omezte počet stránek na jedno spuštění, aby chybná logika nevytvořila nekonečný cyklus. Dostupné zdroje potvrzují název parametru a přítomnost polí `cursor` a `has_more` v pozorovaném schématu, negarantují však úplnost výsledků.

Při sledování několika vyhledávacích frází ukládejte frázi společně s ID videa a časem sběru. Pak můžete vytvářet přehledy podle dotazů, porovnávat výsledky mezi jednotlivými spuštěními a posílat nová ID do fronty pro další klasifikaci. Takový systém popisuje získané výsledky vyhledávání; jeho datová sada závisí na dotazu, regionu, čase a položkách, které API skutečně vrátilo.

Kontrolujte kvalitu dat, nejen úspěšnost požadavku

Po normalizaci je užitečné sledovat jednoduché technické ukazatele vlastního datového toku: počet záznamů z každého pole, počet jedinečných ID, podíl položek bez ID a podíl položek bez statistik. Jde o metriky zpracování konkrétní odpovědi, nikoli o hodnocení popularity videí. Například nárůst počtu položek bez `play_count` znamená, že analytika má uložit neznámou hodnotu a zaznamenat úplnost pole, místo aby dosadila nulu.

Nevážte další výpočty na předpokladu, že každé video má nutně stejnou sadu statistik. Při ukládání nezpracovaných dat zachovejte celý JSON; pro analytickou tabulku vyberte jen potřebná pole a připusťte `NULL`. Pokud se forma odpovědi změní, archiv původních dat umožní znovu spustit normalizátor bez opakovaného požadavku.

Klíč API předávejte prostřednictvím tajných údajů CI nebo proměnných prostředí orchestrátoru. Nevkládejte ho do URL ukládaných do logů, nevypisujte objekt parametrů požadavku a neukládejte hodnotu klíče společně s původními odpověďmi. Pokud se úloha spouští podle plánu, přidejte časový limit požadavku, zpracování chyb HTTP a opakované pokusy s prodlevou; kurzor ukládejte vždy jen ke konkrétnímu vyhledávacímu dotazu, abyste nemíchali stránky různých výsledků.

Výsledek: jednotná tabulka místo vynechaných videí

Po normalizaci dostane navazující kód jediný seznam videí bez ohledu na to, zda položka přišla v `aweme_list`, nebo v `search_item_list[].aweme_info`. ID umožňuje odstranit duplicity a nepovinná pole zůstávají výslovně prázdná. Tím se snižuje riziko prázdných reportů způsobených čtením jediného pole a další krok — export, filtrování nebo klasifikace — je předvídatelnější.

Ověření můžete začít na stránce TikTok Scraper API, kde je uveden základní bod API a odkaz na demo. K integraci použijte oficiální dokumentaci a nejprve otestujte zpracování na malém počtu položek; v případě potřeby zvyšte `count` a pokračujte ve výsledcích pomocí zdokumentovaného kurzoru. Výsledkem bude přehledná datová vrstva pro vaše úlohy, nikoli předpoklad úplného pokrytí TikToku.