Zo verlies je geen TikTok-zoekresultaten bij het verwerken van JSON

Bij het zoeken naar video’s op TikTok via een API staan de video’s mogelijk niet in de array die een verwerker als eerste verwacht. In een gecontroleerde jsonscraper-respons op een verzoek naar ` /searchVideo` was het veld `aweme_list` leeg en stonden de items met videogegevens in `search_item_list[].aweme_info`. Als code alleen `aweme_list` uitleest, slaat die nul video’s op, hoewel de respons wel gevonden video’s bevat. Voor ontwikkelaars is dit een concrete betrouwbaarheidskwestie: haal gegevens uit beide vormen en normaliseer ze tot één lijst voordat je ze in een database opslaat of naar een rapport doorstuurt.

Je kunt een live voorbeeld en de beschrijving van het endpoint raadplegen in de API-specificatie van jsonscraper en de documentatie van het TikTok-endpoint. De schemaopname in de specificatie is gedateerd op 25 oktober 2026; ze toont de structuur van een specifieke respons en garandeert niet dat elk veld in elk volgend verzoek aanwezig is.

Waarom een parser een lege lijst kan retourneren

Het endpoint `GET https://tiktok.evelode.com/searchVideo` zoekt video’s op basis van de verplichte parameter `keyword`. De documentatie vermeldt ook `cursor`, `count`, `cache_timeout`, `date_posted`, `sort_by` en `region`. In het schema van de waargenomen respons bevat het bovenliggende object `status` en een genest object `tiktok`; daarin staan `cursor`, `has_more`, `status_code`, `aweme_list` en `search_item_list`.

Bij een specifieke waarneming van een verzoek met een trefwoord en `count=3` bleek de array `aweme_list` leeg. Tegelijkertijd bevatte `search_item_list` items waarvan de videogegevens in `aweme_info` stonden. Deze objecten konden video-ID’s, bijschriften, publicatie-URL’s, auteurs en statistieken bevatten, zoals het aantal weergaven, likes of reacties. De beschreven velden weerspiegelen het waargenomen schema; de verwerker moet ontbrekende waarden desondanks kunnen verwerken.

De praktische conclusie is dat een geslaagd HTTP-verzoek en een niet-lege array in één verwacht veld twee verschillende controles zijn. Controleer eerst de externe status en of `tiktok` aanwezig is, en verzamel daarna video’s uit elke gedocumenteerde locatie. Bewaar voor analytics de ID en de oorspronkelijke respons: zo kun je nagaan hoe een specifiek item is opgehaald en genormaliseerd.

Normaliseer de respons voordat je die opslaat

Een handige grens tussen de API en je eigen systeem is een functie die het geneste object `tiktok` accepteert en uniforme items retourneert. De functie moet beide arrays verwerken, niet-dictionary- of lege items overslaan en dubbele video’s op basis van `aweme_id` verwijderen. Laat tellers leeg wanneer de provider ze niet heeft teruggegeven: nul zou een gemeten waarde betekenen, terwijl `None` aangeeft dat het veld ontbreekt.

Hieronder staat een minimaal voorbeeld voor Python 3.8+. Het voert één verzoek uit, controleert de transport- en de bovenliggende status, normaliseert beide resultaatvormen en drukt de geselecteerde velden af. De sleutel wordt uit een omgevingsvariabele gelezen en niet naar het log geschreven.

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

Installeer de afhankelijkheid met de opdracht python -m pip install requests, stel `JSONSCRAPER_TIKTOK_LICENSE_KEY` in de uitvoeromgeving in en sla het bestand bijvoorbeeld op als `search_videos.py`. De verzoekparameters komen overeen met de gedocumenteerde namen: `keyword`, `count` en `region`; `license_key` wordt als queryparameter doorgegeven. De code gaat ervan uit dat de respons `status: "ok"` bevat, zoals in het vastgelegde voorbeeld. Als de API een andere status retourneert, stopt de verwerking voordat een twijfelachtige structuur verder wordt doorgegeven.

Maak van het voorbeeld een herhaalbare gegevensverzameling

Voor een eenmalige export volstaat het om de genormaliseerde items naar JSON Lines of een tabel te schrijven. Voeg in een doorlopend proces ook het bewaren van de oorspronkelijke respons toe, samen met het tijdstip van ophalen en de zoekopdracht. In een aparte tabel met genormaliseerde video’s kan `aweme_id` als sleutel dienen: een herhaald resultaat werkt de bestaande registratie bij, terwijl dezelfde ID in twee arrays geen duplicaat oplevert.

Om de volgende pagina op te vragen, schrijft de documentatie de parameter `cursor` voor: geef de waarde door die je in de vorige respons hebt ontvangen. Behandel deze als een ondoorzichtig token — sla hem op en stuur hem ongewijzigd terug. De paginering moet stoppen wanneer `has_more` aangeeft dat er geen vervolg is of wanneer de API geen bruikbare cursor verstrekt; beperk het aantal pagina’s per uitvoering zodat foutieve logica geen oneindige lus veroorzaakt. De vastgelegde bronnen bevestigen de parameternaam en de aanwezigheid van `cursor` en `has_more` in het waargenomen schema, maar garanderen geen volledige resultaten.

Als je meerdere zoektermen monitort, bewaar dan de zoekterm naast de video-ID en het verzameltijdstip. Zo kun je uitsplitsingen per zoekopdracht maken, resultaten van verschillende uitvoeringen vergelijken en nieuwe ID’s naar een wachtrij voor verdere classificatie sturen. Zo’n systeem beschrijft de ontvangen zoekresultaten; de dataset is afhankelijk van de zoekopdracht, regio, tijd en de API-items die daadwerkelijk zijn geretourneerd.

Controleer de gegevenskwaliteit, niet alleen of het verzoek is geslaagd

Na normalisatie is het nuttig om eenvoudige technische statistieken van je pipeline bij te houden: het aantal records uit elke array, het aantal unieke ID’s, het aandeel items zonder ID en het aandeel items zonder statistieken. Dit zijn verwerkingsmetingen van een specifieke respons, geen inschattingen van de populariteit van video’s. Een toename van het aantal items zonder `play_count` betekent bijvoorbeeld dat analytics de waarde als onbekend moet bewaren en de volledigheid van het veld moet markeren, in plaats van nul in te vullen.

Koppel verdere berekeningen niet aan de aanname dat elke video dezelfde statistieken bevat. Bewaar voor ruwe gegevens de volledige JSON; selecteer voor een analytische tabel alleen de benodigde velden en sta `NULL` toe. Als de responsvorm verandert, kun je met het oorspronkelijke archief de normalisatie opnieuw uitvoeren zonder opnieuw een verzoek te doen.

Geef de API-sleutel door via CI-geheimen of omgevingsvariabelen van de orchestrator. Neem hem niet op in URL’s die in logs worden opgeslagen, druk het object met verzoekparameters niet af en bewaar de sleutel niet samen met de oorspronkelijke responsen. Voeg bij geplande uitvoeringen een time-out voor verzoeken, verwerking van HTTP-fouten en nieuwe pogingen met een pauze toe. Bewaar de cursor alleen samen met de bijbehorende zoekopdracht, zodat pagina’s van verschillende zoekresultaten niet door elkaar raken.

Resultaat: één tabel in plaats van gemiste video’s

Na normalisatie krijgt downstream-code één lijst met video’s, ongeacht of een item uit `aweme_list` of uit `search_item_list[].aweme_info` kwam. Met de ID kun je duplicaten verwijderen, terwijl optionele velden expliciet leeg blijven. Dat verkleint het risico op lege rapporten doordat slechts één array wordt uitgelezen en maakt de volgende stap — exporteren, filteren of classificeren — voorspelbaar.

Je kunt beginnen met controleren op de pagina van de TikTok Scraper API, waar het basisadres van de API wordt vermeld en je naar een demo kunt gaan. Gebruik voor de integratie de officiële documentatie en test de verwerking eerst met een klein aantal items; verhoog indien nodig `count` en ga verder met de gedocumenteerde cursor. Het resultaat is een overzichtelijke datalaag voor je eigen taken, geen aanname dat TikTok volledig wordt afgedekt.