TikTok: zo controleer je of zoekmonitoring echt werkt

Een HTTP 200 garandeert niet dat de dagelijkse TikTok-monitoring video’s heeft verzameld. Zoekresultaten kunnen staan in aweme_list of in search_item_list[].aweme_info; een script dat alleen de eerste array uitleest, kan zonder foutmelding eindigen en een leeg rapport opslaan. Een betrouwbare controle bevestigt afzonderlijk de transport- en toepassingsstatus, haalt beide ondersteunde structuurvarianten op en registreert hoeveel unieke video’s tijdens deze uitvoering zijn verzameld.

Wat je precies moet diagnosticeren

Stel je de volgende taak voor: een team verzamelt elke ochtend openbare video’s op basis van meerdere zoekopdrachten om nieuwe berichten over een product op te merken. Een belangrijk resultaat van dit proces is een reproduceerbare lijst met gevonden records, inclusief beschrijving, auteur, publicatiedatum en beschikbare statistieken. Als het rapport plotseling leeg is, kan dat komen door de verwerking van JSON, een gewijzigde resultatenset, opnieuw getoonde video’s die al bekend zijn of een echte aanvraagfout. Eén getal, zoals de lengte van aweme_list, helpt niet om deze gevallen van elkaar te onderscheiden.

In de TikTok Scraper API van jsonscraper accepteert de zoekroute /searchVideo de verplichte parameter keyword en de aanvullende parameters count, cursor, date_posted, sort_by en region. De documentatie van de route beschrijft paginering via cursor; geef deze door als een ondoorzichtige waarde uit het vorige antwoord. De parameter count bepaalt het gewenste aantal resultaten, maar garandeert niet dat alle berichten worden gevonden.

Splits de controle op in vier signalen

Een bruikbare diagnose bestaat uit vier onafhankelijke controles. Ten eerste is de HTTP-aanvraag succesvol afgerond. Ten tweede is de buitenste status van het antwoord gelijk aan ok en komt de interne tiktok.status_code overeen met een succesvol antwoord. Ten derde is het object tiktok aanwezig en worden records opgehaald uit beide gedocumenteerde locaties in het antwoord. Ten vierde blijven na deduplicatie records over met ID’s die geschikt zijn om op te slaan. Bewaar in het logboek het aantal opgehaalde items vóór en na deduplicatie: het verschil laat zien of er tijdens de normalisatie duplicaten zijn ontstaan.

Laat ontbrekende velden leeg in plaats van ze door verzonnen waarden te vervangen. Zo kan het aantal weergaven bij een bepaald record ontbreken. Door de oorspronkelijke JSON naast de genormaliseerde rij op te slaan, kun je later controleren of er informatie verloren is gegaan tijdens het uitlezen of dat die al ontbrak in het oorspronkelijke antwoord.

Een minimale aanvraag en normalisatie in Python

De specificatie van jsonscraper vermeldt het basisadres https://tiktok.evelode.com en het meegeven van de sleutel in de queryparameter license_key. Het onderstaande voorbeeld gebruikt de gedocumenteerde parameters; de sleutel wordt uit een omgevingsvariabele gelezen en niet in het logboek weergegeven. Installeer de afhankelijkheid met python -m pip install requests en stel vervolgens JSONSCRAPER_TIKTOK_LICENSE_KEY in de omgeving in.

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):
    """Verzamel video's uit beide bekende structuren van een zoekantwoord."""
    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": "voorbeeldzoekopdracht over een product",
        "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 gaf een buitenste status terug die niet gelijk is aan ok")

    tiktok = payload.get("tiktok")
    if not isinstance(tiktok, dict):
        raise RuntimeError("Het object tiktok ontbreekt in het antwoord")

    if tiktok.get("status_code") != 0:
        raise RuntimeError("De interne status_code is niet gelijk aan de succesvolle waarde 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()

Het script controleert de transportlaag met raise_for_status() en controleert daarna de buitenste status, de aanwezigheid van het object tiktok en de interne status_code. Vervolgens haalt het records op uit twee zoekstructuren, dedupliceert het deze op basis van aweme_id en slaat het een momentopname met de verzameltijd op. Als er geen geschikte records zijn, bevat het bestand nog steeds informatie over de uitvoering. Zo kun je een opgeslagen leeg resultaat onderscheiden van een ontbrekend rapport.

Zo maak je van momentopnamen een signaal voor het team

Voer het script volgens een schema uit met cron, CI of een workflowplanner. Bewaar voor elke zoekopdracht afzonderlijke momentopnamen of voeg het trefwoord toe aan de bestandsnaam. In een statustabel volstaan de uitvoeringstijd, status, het aantal opgehaalde en unieke records en de vlag has_more. Het is nuttig een melding te versturen bij een aanvraagfout, ontbrekende verplichte onderdelen van het antwoord of een sterke verandering in het aantal opgehaalde records ten opzichte van de eigen historie.

Een dergelijke vergelijking brengt afwijkingen in de pipeline aan het licht, maar verklaart op zichzelf niet de oorzaak. Een lager aantal resultaten kan de samenstelling van de huidige resultatenlijst weerspiegelen en hoeft niet te wijzen op een storing van de API of parser. Bewaar daarom de oorspronkelijke JSON, vergelijk dezelfde parameters en controleer de gevonden ID’s. Kies de meldingsdrempel op basis van waarnemingen voor je eigen zoekopdracht, niet op basis van een universeel getal.

Gebruik voor paginering de cursor uit het antwoord en stop zodra de API aangeeft dat er geen volgende resultaten zijn. Bewaar de gebruikte cursors en aanvraagparameters, zodat de uitvoering reproduceerbaar is. Met de parameters date_posted en sort_by kun je een tijdsfilter en sortering instellen; als de taak reproduceerbare vergelijkingen vereist, houd deze dan bij elke uitvoering gelijk.

Zo lees je het resultaat

Na de invoering heeft het team een controleerbaar antwoord op drie praktische vragen: is de aanvraag uitgevoerd, waar staan de resultaten in de JSON en hoeveel unieke video’s zijn in de opgeslagen momentopname opgenomen? Dat verkort de weg van een lege tabel naar een diagnose: controleer eerst de statussen en structuur, en daarna de parameters, duplicaten en inhoud van het oorspronkelijke antwoord.

Het antwoordschema en de beschikbare velden kunnen per record verschillen. Bij een livecontrole van jsonscraper op 25 oktober 2026 gaf een zoekopdracht velden terug voor de ID, beschrijving, auteur en statistieken; waarden voor een specifiek record moeten als optioneel worden beschouwd. Een werkrapport bewaart de gegevens die daadwerkelijk zijn ontvangen en vervangt ontbrekende waarden niet door nullen.

Je kunt beginnen op de pagina van de TikTok Scraper API en de exacte routes en parameters controleren in de officiële API-documentatie. Deze controle is nuttig voordat je monitoring start: het rapport wordt een waarneembaar resultaat waarvan de kwaliteit te diagnosticeren is.