Michael JohnsonNach dem Start einer App oder einer neuen Funktion verteilt sich das Feedback schnell auf kurze Videos. Ein Marketingmitarbeiter findet manuell einige Clips und schickt die Links in einen Chat. Später kann der Analyst nicht mehr nachvollziehen, welche Beiträge bereits berücksichtigt wurden und wie sich die Aufrufzahlen verändert haben. Eine praktische Lösung besteht darin, regelmäßig Suchergebnisse für mehrere beständige Suchanfragen zu erfassen, die ursprünglichen Antworten zu speichern und den Bericht anhand bestätigter Felder zu erstellen.
In diesem Leitfaden richten wir die Erfassung für einen konkreten Fall ein: Ein Team hat eine neue Funktion veröffentlicht und möchte wöchentlich öffentliche TikTok-Videos beobachten, deren Beschreibung den Produktnamen, eine Schlüsselfunktion oder ein typisches Nutzerproblem enthält. Dabei handelt es sich um die Beobachtung einer gefundenen Suchstichprobe: Die API liefert Ergebnisse entsprechend der Abfrage und den Parametern, aber keine garantierte Liste aller Beiträge zum Produktstart.
Legen Sie zuerst fest, welches Signal das Team benötigt
Eine hohe Zahl von Aufrufen allein erklärt nur unzureichend, was als Nächstes zu tun ist. Nützlicher ist für das Team zu wissen, welche Fragen wiederholt auftreten, welche Szenarien Menschen zeigen und welche Videos deutliche öffentliche Reaktionen erhalten. Formulieren Sie daher zunächst mehrere Suchbegriffe und entscheiden Sie, welche Felder in den Bericht aufgenommen werden.
Für den Start eines Tools zur Planung von Beiträgen könnten Sie beispielsweise die Suchanfragen „Produktname“, „Content-Planer“ und „TikTok-Beiträge planen“ prüfen. Die Formulierungen sollten verschiedene Arten abdecken, wie Menschen dasselbe Thema beschreiben könnten. Halten Sie sie zusammen mit dem Startdatum der Beobachtung und der Region fest, damit spätere Exporte bei gleichen Einstellungen vergleichbar sind.
Eine minimale Tabelle kann Erfassungszeitpunkt, Suchbegriff, Video-ID, Link, Beschreibung, Autorname, Autor-ID sowie verfügbare Werte für Aufrufe, Likes und Kommentare enthalten. Die TikTok Scraper API dokumentiert für Suchergebnisse Felder wie aweme_id, desc, share_url, Angaben zum Autor und einige Statistiken. Prüfen Sie jedes konkrete Feld in jedem Objekt: Einzelne Kennzahlen können fehlen.
Richten Sie die dokumentierte Suche ein
Verwenden Sie für die Videosuche die GET-Route /searchVideo unter der Basisadresse https://tiktok.evelode.com. In der Dokumentation sind der erforderliche Parameter keyword sowie die zusätzlichen Parameter count, cursor, date_posted, sort_by, region und cache_timeout aufgeführt. Zu den zulässigen Werten für den Datumsfilter gehört this-week; mögliche Sortierungen sind relevance, most-liked und date-posted. Prüfen Sie Zweck und Namen anhand des Routenverzeichnisses der TikTok API.
Der Lizenzschlüssel wird als Query-Parameter license_key übergeben. Lesen Sie ihn in einem produktiven Skript aus der Umgebungsvariable JSONSCRAPER_TIKTOK_LICENSE_KEY, hinterlegen Sie das Geheimnis nicht im Quellcode und geben Sie es nicht in Protokollen aus. Dieses Beispiel setzt Python 3.8+ voraus und verwendet das Paket requests:
import os
import requests
BASE_URL = "https://tiktok.evelode.com"
API_KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
def search_videos(keyword, cursor=None):
params = {
"license_key": API_KEY,
"keyword": keyword,
"count": 20,
"date_posted": "this-week",
"sort_by": "date-posted",
"region": "US",
}
if cursor is not None:
params["cursor"] = cursor
response = requests.get(
f"{BASE_URL}/searchVideo",
params=params,
timeout=30,
)
response.raise_for_status()
payload = response.json()
if payload.get("status") != "ok":
raise RuntimeError("Die TikTok API hat einen anderen Status als ok zurückgegeben")
return payload["tiktok"]
result = search_videos("content planning app")
print("Gefundene Objekte:", len(result.get("aweme_list", [])))Das Skript prüft auf HTTP-Fehler und den äußeren Antwortstatus. Eine erfolgreiche HTTP-Antwort garantiert für sich genommen nicht, dass die Suche Videos enthält: Bei einer leeren Stichprobe kann die Liste leer sein. Speichern Sie für den ersten Durchlauf am besten die vollständige Antwort in einem geschützten Speicher, um die tatsächlichen Objekte mit der Tabelle normalisierter Felder abzugleichen.
Verarbeiten Sie beide Varianten der Suchantwort
Die Suchergebnisse haben eine wichtige Besonderheit in ihrer Struktur. Videos können direkt in tiktok.aweme_list enthalten sein oder innerhalb von tiktok.search_item_list[].aweme_info eintreffen. Liest der Handler nur die erste Liste aus, kann er Ergebnisse übersehen, die in der zweiten Variante enthalten sind.
Ergänzen Sie einen kleinen Normalisierer, der beide Strukturen unterstützt und Elemente ohne verschachteltes Videoobjekt problemlos überspringt:
def extract_awemes(tiktok):
items = list(tiktok.get("aweme_list") or [])
for item in tiktok.get("search_item_list") or []:
aweme = item.get("aweme_info")
if aweme:
items.append(aweme)
return items
def normalize(aweme, keyword, collected_at):
author = aweme.get("author") or {}
stats = aweme.get("statistics") or {}
return {
"collected_at": collected_at,
"keyword": keyword,
"video_id": aweme.get("aweme_id"),
"posted_at": aweme.get("create_time"),
"description": aweme.get("desc"),
"share_url": aweme.get("share_url"),
"author_id": author.get("uid"),
"author_name": author.get("nickname"),
"views": stats.get("play_count"),
"likes": stats.get("digg_count"),
"comments": stats.get("comment_count"),
"shares": stats.get("share_count"),
}Ein fehlender Wert bleibt None. Ersetzen Sie ihn nicht durch null: Null bedeutet einen gemessenen Wert, während None festhält, dass das Feld nicht mitgeliefert wurde. Dieser Unterschied wirkt sich auf Durchschnittswerte, Anteile und alle Schlussfolgerungen für das Team aus.
Bewahren Sie die Historie auf, nicht nur den aktuellen Stand
Um Entwicklungen zu erkennen, speichern Sie einzelne Beobachtungen. Die Video-ID eignet sich zur Deduplizierung von Beiträgen, aber nicht dazu, den Verlauf zu löschen: Taucht dasselbe Video bei der nächsten Erfassung erneut auf, entsteht ein neuer Beobachtungspunkt. Beispielsweise kann sich ein eindeutiger Schlüssel für die Beobachtungstabelle aus video_id und collected_at zusammensetzen; speichern Sie den Link und die Beschreibung zur einfacheren Überprüfung im Datensatz.
Ein minimales SQLite-Schema eignet sich für einen Prototyp:
import sqlite3
conn = sqlite3.connect("tiktok_observations.sqlite3")
conn.execute("""
CREATE TABLE IF NOT EXISTS observations (
video_id TEXT NOT NULL,
collected_at TEXT NOT NULL,
keyword TEXT NOT NULL,
posted_at INTEGER,
description TEXT,
share_url TEXT,
author_id TEXT,
author_name TEXT,
views INTEGER,
likes INTEGER,
comments INTEGER,
shares INTEGER,
PRIMARY KEY (video_id, collected_at, keyword)
)
""")
conn.commit()Normalisieren Sie in der Praxis den Erfassungszeitpunkt auf UTC, speichern Sie das ursprüngliche JSON separat und ergänzen Sie eine Spalte für die Schema-Version. Mit der ursprünglichen Antwort lässt sich die Umwandlung erneut prüfen, wenn sich die Struktur neuer Objekte von der gewohnten unterscheidet. Speichern Sie bei Beiträgen, die über mehrere Suchanfragen gefunden wurden, die passenden Suchbegriffe in einer separaten verknüpften Tabelle oder fassen Sie sie beim Erstellen des Berichts zusammen.
Paginierung: Fahren Sie nur mit dem Cursor aus der Antwort fort
Der Parameter cursor dient dazu, die Suche fortzusetzen. Sein Wert wird der vorherigen Antwort entnommen und unverändert zurückgegeben. Die Verarbeitung endet, wenn has_more keine Fortsetzung mehr anzeigt oder ein festgelegtes Limit erreicht ist. Behandeln Sie den Cursor als undurchsichtig: Berechnen Sie ihn nicht selbst und ersetzen Sie ihn nicht durch einen Seitenzähler.
def collect_pages(keyword, max_pages=3):
cursor = None
collected = []
for _ in range(max_pages):
page = search_videos(keyword, cursor)
collected.extend(extract_awemes(page))
if not page.get("has_more"):
break
cursor = page.get("cursor")
if cursor is None:
break
return collectedEine Begrenzung der Seitenzahl macht die regelmäßige Aufgabe hinsichtlich der Anzahl der Anfragen vorhersehbar. Protokollieren Sie die Seitenzahl und den Wert von has_more: So erhält der Stichprobenbericht den nötigen Kontext. Auch mit Paginierung beschreibt das Ergebnis lediglich die erhaltenen API-Antworten und das festgelegte Erfassungslimit; es ist keine Schätzung sämtlicher Beiträge auf der Plattform.
Erstellen Sie einen wiederholbaren Bericht
Führen Sie die Erfassung wöchentlich oder häufiger nach einem Zeitplan aus, wenn das Team häufiger Signale benötigt. Halten Sie für jeden Durchlauf die Suchanfragen, Parameter, den Zeitpunkt, die Anzahl der erhaltenen Objekte und die Anzahl eindeutiger IDs fest. Zählen Sie getrennt die Beiträge, die in diesem Durchlauf erstmals entdeckt wurden, und jene, die bereits zuvor aufgetaucht sind.
Vier einfache Ansichten sind im Bericht hilfreich:
- Neue Videos: Links, Beschreibungen, Veröffentlichungsdatum und Suchbegriff, über den das Video gefunden wurde.
- Wiederkehrende Themen: Gruppierung der Beschreibungen anhand manuell festgelegter Kategorien, etwa „Konfigurationsfehler“, „Funktionswunsch“ und „Szenarioübersicht“.
- Öffentliche Reaktionen: verfügbare Aufrufe, Likes, Kommentare und geteilte Beiträge, zusammen mit dem Beobachtungszeitpunkt.
- Zu prüfende Signale: neue Formulierungen, häufige Fragen oder Videos, die ein Mitarbeiter genauer untersuchen sollte.
Bezeichnen Sie den Unterschied zwischen zwei Momentaufnahmen nicht als „neue Likes“, ohne Semantik und Aktualität der Werte in der Antwort zu prüfen. Korrekt sind Formulierungen wie „Kennzahlenwert in der zuletzt erhaltenen Antwort“ und „Unterschied zwischen den gespeicherten Momentaufnahmen“. So sieht das Team, was genau berechnet wurde, und kann den ursprünglichen Beitrag öffnen, bevor es eine Entscheidung trifft.
Nutzen Sie KI für die Klassifizierung, nicht als Ersatz für die Erfassung
Nach der Normalisierung können Sie Videobeschreibungen an ein Modell senden, das sie vorab festgelegten Kategorien zuordnet. Übermitteln Sie nur die erforderlichen Textfelder und bitten Sie um ein strukturiertes Ergebnis: Kategorie, kurze Begründung, Konfidenzniveau und den Beschreibungsausschnitt, auf dem die Kennzeichnung beruht. Speichern Sie den ursprünglichen Beitrag zusammen mit der Kennzeichnung, damit Analysten strittige Fälle prüfen können.
Der Arbeitsablauf bleibt einfach: Ein Scheduler startet die Erfassung; Python prüft die Antwort und speichert das JSON; ein separater Prozess normalisiert neue Datensätze; ein Klassifikator verarbeitet nur neue Beschreibungen; der Bericht wird aus der Datenbank erstellt und an den vom Team ausgewählten Kanal gesendet. Die TikTok Scraper API selbst liefert Suchdaten. Die Klassifizierung und der Versand des Berichts gehören zu Ihrer Integrationslogik, die sich mit Python, n8n oder Make umsetzen lässt.
Um Störsignale zu verringern, legen Sie vor dem Senden an das Modell ein Kategorienverzeichnis fest und überprüfen Sie regelmäßig eine manuell gekennzeichnete Stichprobe. Für kurze oder mehrdeutige Beschreibungen ist der Status „Kontext nicht ausreichend“ sinnvoller als eine erzwungene Kategorieauswahl. KI-Kennzeichnungen helfen bei der Priorisierung der Prüfwarteschlange; Schlussfolgerungen über Nutzerprobleme sollten Sie jedoch durch das Lesen der Beiträge und den Vergleich mehrerer Beobachtungen bestätigen.
Fehler, Wiederholungsversuche und sicherer Umgang mit dem Schlüssel
Eine Netzwerkanfrage kann mit einer Zeitüberschreitung oder einem vorübergehenden Fehler scheitern oder eine Antwort liefern, die sich nicht als JSON parsen lässt. Trennen Sie die Verarbeitung in Schritte: Anfrage, Prüfung des HTTP-Statuscodes, JSON-Parsing, Prüfung des äußeren Status, Normalisierung und Speicherung. Verwenden Sie bei vorübergehenden Fehlern eine begrenzte Zahl von Wiederholungsversuchen mit zunehmender Wartezeit. Protokollieren Sie dauerhafte Fehler zur späteren Untersuchung, ohne den Durchlauf als erfolgreich zu kennzeichnen.
Speichern Sie den Schlüssel in einem Secret-Manager der Laufzeitumgebung oder in einer Umgebungsvariable. Da die API license_key in der Query-Zeichenfolge entgegennimmt, sollten Sie nicht die vollständige URL und die Anfrageparameter protokollieren: Sie würden das Geheimnis enthalten. Notieren Sie zur Diagnose die Route, den Antwortcode, die Dauer, den Suchbegriff und die Auftrags-ID, und entfernen Sie den Schlüssel aus den Protokollen.
Legen Sie Zeitplan und Umfang der Stichprobe entsprechend Ihrer Aufgabe und den Nutzungsbedingungen der Plattform fest. Die Erfassung öffentlicher Daten sollte auf das tatsächlich für die Analyse Erforderliche beschränkt bleiben; die Speicherung von Beschreibungen, Links und Autoren-IDs sollte in internen Teamrichtlinien geregelt sein. API-Antworten und Kennzahlen können unvollständig sein oder sich zwischen Beobachtungen ändern. Daher sollte der Bericht den Erfassungszeitpunkt und die Herkunft jeder Zeile festhalten.
Ergebnis: von manuell geteilten Links zu einer überprüfbaren Historie
Nach der Einrichtung erhält das Team eine regelmäßig aktualisierte Liste gefundener Videos, die ursprünglichen Antworten für Audits, eine Tabelle der verfügbaren öffentlichen Kennzahlen und eine Übersicht wiederkehrender Themen. So lassen sich Fragen zu einer neuen Funktion schneller erkennen, Beispiele für Nutzungsszenarien finden und Beiträge zur manuellen Analyse auswählen. Der Vergleich der Momentaufnahmen zeigt, wie sich die gespeicherten Werte bereits gefundener Videos verändern; das Protokoll der Suchanfragen erklärt, wie die Stichprobe zustande kam.
Beginnen Sie mit einer Suchanfrage und einer kleinen Seitenbegrenzung, prüfen Sie die tatsächliche Antwortstruktur und ergänzen Sie anschließend weitere Formulierungen und einen Zeitplan. Legen Sie vor der Überführung des Prototyps in die Produktionsumgebung Regeln für Deduplizierung, Speicherung und Fehlerbehandlung fest. Die aktuellen Routen und Parameter finden Sie in der offiziellen API-Dokumentation; eine Beschreibung der Funktionen und den Einstieg in den Test bietet die Seite zur TikTok Scraper API.
