TikTok-Suchergebnisse bei der JSON-Verarbeitung nicht verlieren

Bei der Suche nach TikTok-Videos über eine API liegen die Videos möglicherweise nicht in dem Array, das ein Handler zuerst erwartet. In einer geprüften Antwort von jsonscraper war das Feld `aweme_list` bei einer Anfrage an `/searchVideo` leer, während Videoangaben unter `search_item_list[].aweme_info` zu finden waren. Liest der Code nur `aweme_list`, speichert er null Videos, obwohl die Antwort Treffer enthält. Für Entwickler ist das eine konkrete Zuverlässigkeitsaufgabe: Beide Datenformen extrahieren und vor dem Speichern in einer Datenbank oder der Weitergabe an einen Bericht in einer einheitlichen Liste normalisieren.

Ein geprüftes Beispiel und die Beschreibung des Endpoints finden Sie in der API-Spezifikation von jsonscraper und in der Dokumentation des TikTok-Endpoints. Der Schema-Snapshot in der Spezifikation ist auf den 25. Oktober 2026 datiert. Er zeigt die Struktur einer konkreten Antwort, garantiert aber nicht, dass jedes Feld auch in jeder späteren Anfrage vorhanden ist.

Warum ein Parser eine leere Liste zurückgeben kann

Der Endpoint `GET https://tiktok.evelode.com/searchVideo` sucht anhand des Pflichtparameters `keyword` nach Videos. In der Dokumentation werden außerdem `cursor`, `count`, `cache_timeout`, `date_posted`, `sort_by` und `region` aufgeführt. Im Schema der beobachteten Antwort enthält das oberste Objekt `status` und ein verschachteltes Objekt `tiktok`; darin befinden sich `cursor`, `has_more`, `status_code`, `aweme_list` und `search_item_list`.

Bei einer konkreten Anfrage mit einem Suchbegriff und `count=3` war das Array `aweme_list` leer. `search_item_list` enthielt dagegen Elemente, deren Videoangaben unter `aweme_info` lagen. Diese Objekte konnten Video-IDs, Bildunterschriften, Veröffentlichungs-URLs, Angaben zum Autor und Statistiken enthalten, etwa Aufruf-, Like- oder Kommentarzahlen. Die genannten Felder entsprechen dem beobachteten Schema; der Handler sollte dennoch auch mit fehlenden Werten umgehen können.

Die praktische Schlussfolgerung: Eine erfolgreiche HTTP-Anfrage und ein nicht leeres Array in einem erwarteten Feld sind zwei verschiedene Prüfungen. Prüfen Sie zuerst den äußeren Status und das Vorhandensein von `tiktok`. Sammeln Sie anschließend Videos aus allen dokumentierten Feldern. Für Analysezwecke sollten Sie die ID und die ursprüngliche Antwort speichern, damit sich nachvollziehen lässt, wie ein bestimmter Eintrag extrahiert und normalisiert wurde.

Antwort vor dem Speichern normalisieren

Eine sinnvolle Schnittstelle zwischen API und eigenem System ist eine Funktion, die das verschachtelte Objekt `tiktok` entgegennimmt und einheitliche Elemente zurückgibt. Sie sollte beide Arrays verarbeiten, Nicht-Wörterbuch- oder leere Elemente überspringen und doppelte Videos anhand von `aweme_id` entfernen. Lassen Sie Zähler leer, wenn der Anbieter sie nicht zurückgegeben hat: Null würde einen gemessenen Wert bedeuten, während `None` das Fehlen des Feldes kennzeichnet.

Das folgende Beispiel für Python 3.8+ ist bewusst minimal gehalten. Es sendet eine Anfrage, prüft den Transport- und den obersten Status, normalisiert beide Ergebnisvarianten und gibt ausgewählte Felder aus. Der Schlüssel wird aus einer Umgebungsvariable gelesen und nicht protokolliert.

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

Installieren Sie die Abhängigkeit mit dem Befehl python -m pip install requests, setzen Sie `JSONSCRAPER_TIKTOK_LICENSE_KEY` in der Laufzeitumgebung und speichern Sie die Datei zum Beispiel unter `search_videos.py`. Die Anfrageparameter entsprechen den dokumentierten Namen: `keyword`, `count` und `region`; `license_key` wird als Query-Parameter übergeben. Der Code setzt voraus, dass die Antwort wie im aufgezeichneten Beispiel `status: "ok"` enthält. Gibt die API einen anderen Status zurück, wird die Verarbeitung angehalten, bevor eine zweifelhafte Struktur weitergereicht wird.

Das Beispiel in einen wiederholbaren Abruf verwandeln

Für einen einmaligen Export genügt es, normalisierte Elemente als JSON Lines oder in einer Tabelle zu speichern. Ergänzen Sie bei einem laufenden Prozess die ursprüngliche Antwort sowie den Erfassungszeitpunkt und die Suchanfrage. Eine separate Tabelle normalisierter Videos kann `aweme_id` als Schlüssel verwenden: Ein wiederholter Treffer aktualisiert den Eintrag, und dieselbe ID in beiden Arrays erzeugt kein Duplikat.

Für die nächste Seite nennt die Dokumentation den Parameter `cursor`: Übergeben Sie den Wert, den Sie in der vorherigen Antwort erhalten haben. Behandeln Sie ihn als undurchsichtiges Token und speichern sowie übergeben Sie ihn unverändert. Beenden Sie die Paginierung, wenn `has_more` keine weiteren Ergebnisse anzeigt oder die API keinen brauchbaren Cursor liefert. Begrenzen Sie die Zahl der Seiten pro Lauf, damit eine fehlerhafte Logik keine Endlosschleife auslöst. Die dokumentierten Quellen bestätigen den Parameternamen und das Vorhandensein der Felder `cursor` und `has_more` im beobachteten Schema, garantieren aber keine Vollständigkeit der Ergebnisse.

Wenn Sie mehrere Suchbegriffe überwachen, speichern Sie den Begriff zusammen mit der Video-ID und dem Erfassungszeitpunkt. So können Sie Ergebnisse nach Suchanfrage aufschlüsseln, Trefferlisten zwischen Läufen vergleichen und neue IDs zur weiteren Klassifizierung in eine Warteschlange stellen. Ein solches System bildet die abgerufenen Suchergebnisse ab; der Datensatz hängt von Suchanfrage, Region, Zeitpunkt und den tatsächlich von der API zurückgegebenen Elementen ab.

Datenqualität prüfen, nicht nur den Erfolg der Anfrage

Nach der Normalisierung empfiehlt es sich, einfache technische Kennzahlen für Ihre Pipeline zu erfassen: die Anzahl der Einträge aus jedem Array, die Zahl eindeutiger IDs, den Anteil der Elemente ohne ID und den Anteil der Elemente ohne Statistiken. Diese Kennzahlen beschreiben die Verarbeitung einer konkreten Antwort, nicht die Popularität der Videos. Ein Anstieg der Elemente ohne `play_count` zeigt zum Beispiel, dass die Analyse den unbekannten Wert beibehalten und die Feldvollständigkeit kennzeichnen sollte, statt null einzusetzen.

Verknüpfen Sie nachfolgende Berechnungen nicht mit der Annahme, dass jedes Video immer denselben Satz an Statistiken enthält. Bewahren Sie für Rohdaten das vollständige JSON auf; wählen Sie für die Analysetabelle nur die benötigten Felder aus und erlauben Sie `NULL`. Ändert sich das Antwortformat, können Sie mit dem archivierten Original den Normalisierer erneut ausführen, ohne nochmals eine Anfrage zu senden.

Übergeben Sie den API-Schlüssel über CI-Secrets oder Umgebungsvariablen des Orchestrators. Nehmen Sie ihn nicht in URLs auf, die in Protokollen gespeichert werden, geben Sie das Anfragenparameterobjekt nicht aus und speichern Sie den Schlüssel nicht zusammen mit den ursprünglichen Antworten. Läuft der Abruf nach einem Zeitplan, ergänzen Sie ein Anfragezeitlimit, die Behandlung von HTTP-Fehlern und Wiederholungsversuche mit Pausen. Speichern Sie den Cursor stets zusammen mit der jeweiligen Suchanfrage, damit Seiten verschiedener Trefferlisten nicht vermischt werden.

Das Ergebnis: eine einheitliche Tabelle statt übersehener Videos

Nach der Normalisierung erhält der nachgelagerte Code eine einzige Videoliste – unabhängig davon, ob ein Element aus `aweme_list` oder `search_item_list[].aweme_info` stammt. Anhand der ID lassen sich Duplikate entfernen, während optionale Felder ausdrücklich leer bleiben. Das verringert das Risiko leerer Berichte, die entstehen, weil nur ein Array ausgelesen wird, und macht den nächsten Schritt – Export, Filterung oder Klassifizierung – besser vorhersehbar.

Mit der Prüfung können Sie auf der Seite der TikTok Scraper API beginnen, auf der der API-Basispunkt angegeben ist und eine Demo aufgerufen werden kann. Verwenden Sie für die Integration die offizielle Dokumentation und testen Sie die Verarbeitung zunächst mit wenigen Elementen. Erhöhen Sie bei Bedarf `count` und setzen Sie die Abfrage mit dem dokumentierten Cursor fort. So entsteht eine geordnete Datenschicht für Ihre Aufgaben – keine Behauptung, TikTok vollständig abzudecken.