TikTok: Suchergebnisse in eine wöchentliche Themenliste für den Support verwandeln

Das Supportteam benötigt eine Liste öffentlicher TikTok-Videos, in denen Menschen über eine unklare Funktion sprechen oder Fragen zu einem Produkt stellen. Eine manuelle Suche lässt sich nur schwer auf dieselbe Weise wiederholen, und Such-API-Antworten können Videos an unterschiedlichen Stellen im JSON speichern. Das folgende minimale Python-Skript fragt Ergebnisse anhand von Schlüsselwörtern ab, führt beide Strukturen zusammen, entfernt Duplikate anhand der ID und speichert die gefundenen Einträge als CSV-Datei.

Welches Ergebnis das Skript liefert

Das Ergebnis ist eine Tabelle mit Video-ID, Link, Beschreibung, Veröffentlichungszeitpunkt, Autor und verfügbaren Interaktionszahlen. Das Support- oder Marketingteam kann manuell markieren, welche Themen eine Antwort, eine Aktualisierung der Anleitung oder eine Prüfung im eigenen CRM erfordern. Die Tabelle bildet genau die API-Ergebnisse zu den angegebenen Suchanfragen ab. Betrachten Sie sie als Arbeitsauswahl für die Auswertung, nicht als vollständigen Katalog aller Diskussionen.

Das Skript übernimmt das Sammeln und die erste Sortierung. Es bestimmt nicht automatisch, ob eine Beschreibung eine Frage, eine Beschwerde oder einen Scherz enthält. Eine solche Kennzeichnung sollte nach einer manuellen Prüfung oder durch einen separaten Klassifikator ergänzt werden; dabei sollten der Originaltext und die Begründung der Entscheidung festgehalten werden.

Was abgefragt wird und wie die Antwort aufgebaut ist

Für die Videosuche dokumentiert jsonscraper die GET-Route /searchVideo auf dem Host https://tiktok.evelode.com. Der erforderliche Parameter lautet keyword. Außerdem lassen sich count, Region, Sortierung, Veröffentlichungszeitraum und ein Cursor für die nächste Seite übergeben. Die Suche kann beispielsweise mit mehreren zuvor festgelegten Formulierungen wiederholt werden: dem Namen einer Funktion, einer häufig verwendeten Fehlerbeschreibung und einer kurzen Frage zur Einrichtung. Parameter und zulässige Werte sind in der TikTok-API-Referenz aufgeführt.

Die Suche hat eine wichtige Besonderheit für den Parser: Das Array aweme_list kann leer sein, während sich gefundene Objekte in search_item_list befinden und jedes davon ein aweme_info-Objekt enthält. Der folgende Handler prüft deshalb beide Formen. Ein Antwortbeispiel und die bei einer Prüfung am 25. Oktober 2026 beobachteten Felder finden sich in der ursprünglichen jsonscraper-Spezifikation. Statistikfelder können fehlen; der Code setzt daher keine erfundenen Werte ein.

API-Schlüssel und Suchanfragen vorbereiten

Speichern Sie den Schlüssel in der Umgebungsvariable JSONSCRAPER_TIKTOK_LICENSE_KEY statt in der Quelldatei. In einer Linux- oder macOS-Shell geht das so:

export JSONSCRAPER_TIKTOK_LICENSE_KEY="ihr_schlüssel"

Installieren Sie die Requests-Bibliothek und erstellen Sie die Datei queries.txt mit einem Suchbegriff pro Zeile, zum Beispiel Produktname Einrichtung und Funktionsname funktioniert nicht. Wählen Sie Formulierungen passend zur Sprache Ihrer Zielgruppe und verwalten Sie sie in einer separaten Liste, damit sich wöchentliche Exporte anhand derselben Suchanfragen vergleichen lassen.

python -m pip install requests

Gefundene Videos erfassen und vereinheitlichen

Das Beispiel ist mit Python 3.8 und höher kompatibel. Es führt für jede Formulierung eine Anfrage mit einer Ergebnisbegrenzung aus, prüft HTTP-Fehler und den Status auf oberster Ebene und speichert anschließend nur tatsächlich vorhandene Felder. Doppelte Treffer werden anhand von aweme_id zusammengeführt; alle Suchanfragen, über die ein Video gefunden wurde, landen im Feld keywords. Das Feld collected_at_utc hält den Erfassungszeitpunkt fest, damit sich spätere Durchläufe vergleichen lassen.

import csv
import os
import sys
from datetime import datetime, timezone

import requests

BASE_URL = "https://tiktok.evelode.com/searchVideo"
API_KEY = os.environ.get("JSONSCRAPER_TIKTOK_LICENSE_KEY")

if not API_KEY:
    raise SystemExit("Setzen Sie JSONSCRAPER_TIKTOK_LICENSE_KEY")


def get_items(tiktok):
    """Extrahiert Videos aus beiden dokumentierten Antwortformen der Suche."""
    items = list(tiktok.get("aweme_list") or [])
    for entry in tiktok.get("search_item_list") or []:
        info = entry.get("aweme_info") if isinstance(entry, dict) else None
        if info:
            items.append(info)
    return items


with open("queries.txt", encoding="utf-8") as query_file:
    queries = [line.strip() for line in query_file if line.strip()]

collected_at = datetime.now(timezone.utc).isoformat()
videos = {}

for keyword in queries:
    response = requests.get(
        BASE_URL,
        params={
            "license_key": API_KEY,
            "keyword": keyword,
            "count": 30,
            "region": "US",
            "sort_by": "relevance",
        },
        timeout=30,
    )
    response.raise_for_status()
    payload = response.json()

    if payload.get("status") != "ok":
        print("API-Status für Suchanfrage nicht erfolgreich:", keyword, file=sys.stderr)
        continue

    tiktok = payload.get("tiktok") or {}
    for item in get_items(tiktok):
        video_id = item.get("aweme_id")
        if not video_id:
            continue

        if video_id not in videos:
            author = item.get("author") or {}
            stats = item.get("statistics") or {}
            videos[video_id] = {
                "aweme_id": video_id,
                "keywords": [keyword],
                "description": item.get("desc"),
                "share_url": item.get("share_url"),
                "create_time": item.get("create_time"),
                "author": author.get("unique_id") or author.get("nickname"),
                "play_count": stats.get("play_count"),
                "digg_count": stats.get("digg_count"),
                "comment_count": stats.get("comment_count"),
                "share_count": stats.get("share_count"),
                "collected_at_utc": collected_at,
            }
        elif keyword not in videos[video_id]["keywords"]:
            videos[video_id]["keywords"].append(keyword)

columns = [
    "aweme_id", "keywords", "description", "share_url", "create_time",
    "author", "play_count", "digg_count", "comment_count", "share_count",
    "collected_at_utc",
]
with open("tiktok_support_review.csv", "w", newline="", encoding="utf-8-sig") as output:
    writer = csv.DictWriter(output, fieldnames=columns)
    writer.writeheader()
    for video in videos.values():
        row = dict(video)
        row["keywords"] = " | ".join(row["keywords"])
        writer.writerow(row)

print("Anzahl gespeicherter eindeutiger gefundener Videos:", len(videos))

Die Anfrage wird über den Parameter params gesendet, sodass die Bibliothek Textphrasen korrekt für die URL kodiert. Der Schlüssel wird dabei wie in der Dokumentation beschrieben als Query-Parameter übergeben. Geben Sie die vollständige Anfrage-URL nicht im Anwendungsprotokoll aus. Zur Diagnose können Sie den HTTP-Antwortcode, die Suchphrase und den Startzeitpunkt speichern, sollten aber Geheimnisse und für die Aufgabe unnötige personenbezogene Daten ausschließen.

CSV ohne voreilige Schlüsse auswerten

Die Spalte keywords enthält alle Suchbegriffe, über die ein Video gefunden wurde; collected_at_utc unterscheidet den Erfassungszeitpunkt vom Veröffentlichungszeitpunkt. Die ID eignet sich zum Entfernen von Duplikaten, der Link zur menschlichen Prüfung. Ein leerer Zähler bedeutet, dass das Feld in der jeweiligen Antwort fehlte – nicht, dass der Wert null beträgt.

Ergänzen Sie in einer Arbeitskopie der CSV für die erste Sortierung die Spalten Thema, Signaltyp, Antwort erforderlich und Link zu internem Material. Die Themen sollten zu Ihrem Produkt passen, zum Beispiel Installation, Zahlung, Kompatibilität oder Fehlerbehebung. So wird der Export zu einer Warteschlange für die Auswertung, und die Entscheidung lässt sich anhand des Originalvideos überprüfen.

Erfassung nach Zeitplan ausführen

Führen Sie das Skript zunächst manuell aus und prüfen Sie einige Zeilen und Links. Fügen Sie es anschließend in einen Cronjob, eine CI-Aufgabe oder einen Automatisierungsablauf ein, der einen Python-Prozess starten kann. Speichern Sie für regelmäßige Berichte jeden Export oder fügen Sie Zeilen mit einem eindeutigen Videoschlüssel und dem Datum der Momentaufnahme zu einem Datenspeicher hinzu. So kann das Team neue gefundene Veröffentlichungen von wiederholten Beobachtungen unterscheiden und nachvollziehen, wie sich verfügbare Zähler zwischen den Durchläufen ändern.

Der Parameter cursor ist für das Durchblättern der Ergebnisse vorgesehen und muss aus der Antwort des vorherigen Aufrufs übernommen werden. Die Paginierung ist in dieser minimalen Variante bewusst nicht enthalten: Eine begrenzte Zahl von Suchanfragen lässt sich leichter prüfen und reproduzieren. Wenn Sie Seiten ergänzen, behandeln Sie den Cursor als undurchsichtigen Wert, stoppen Sie anhand des Fortsetzungsindikators und legen Sie eine Höchstzahl von Aufrufen pro Durchlauf fest. Die API-Anfrage liefert eine Auswahl; interpretieren Sie die Zahl der Zeilen nicht als vollständige Abdeckung von TikTok.

Praktische Grenzen der Anwendung

Die Suchergebnisse eignen sich dazu, Videos anhand von Formulierungen zu finden, die dem Team bereits bekannt sind. Sie helfen beim Zusammenstellen von Material zur Klassifizierung, ersetzen aber weder eingehende Kundenanfragen noch die Analyse der eigenen Website oder die Prüfung des Videokontexts. Die Beschreibung gibt möglicherweise nicht den Inhalt des Videos wieder, und verfügbare Kennzahlen spiegeln den Datenstand zum Zeitpunkt des Abrufs wider. Erfassen Sie Themen und Schlussfolgerungen getrennt von den Originalfeldern, damit Mitarbeitende die Klassifizierung erneut prüfen können.

Legen Sie vor Beginn einer regelmäßigen Überwachung fest, wer Zugriff auf den Export hat, wie lange die Daten gespeichert werden und zu welchem Zweck öffentliche Informationen verwendet werden. Speichern Sie nur die für die Produktauswertung benötigten Felder und bevorzugen Sie Links zu den Originalveröffentlichungen, statt Mediendateien zu kopieren. Informationen zu verfügbaren Integrationsoptionen finden Sie auf der Seite zur TikTok Scraper API und in der Dokumentation der Suchroute.