Michael JohnsonNach dem Start einer Kampagne kann es für ein Team nützlich sein, zu prüfen, welche öffentlichen Videos bei der Suche nach ausgewählten Begriffen erscheinen. Eine manuelle Suche lässt sich nur schwer wiederholen und nach einigen Tagen vergleichen. Ein kleiner Collector kann regelmäßig dieselben Suchanfragen ausführen und die Antworten mit Datum und Suchbegriff archivieren, damit Analystinnen und Analysten die Einträge prüfen und eine eigene Zusammenfassung erstellen können.
Diese Anleitung zeigt eine Python-Archivpipeline, die Suchergebnisse für festgelegte Suchbegriffe speichert. Anders als beim Monitoring einzelner Hashtags oder Konten besteht der Schlüssel zum Vergleich darin, dieselben Suchbegriffe wiederholt abzufragen und für jede Antwort einen eigenen Snapshot zu speichern. Die Seite zur TikTok Scraper API von jsonscraper nennt die Basis-URL und die Route GET /searchVideo; laut Dokumentation dieser Route wird der Suchbegriff im erforderlichen Parameter keyword übergeben.
Aufgabe und Grenzen der Messung
Stellen wir uns vor, eine Marketingfachkraft möchte täglich Ergebnisse für einige festgelegte Suchbegriffe erfassen: den Produktnamen, eine Kategorie und eine Formulierung für ein Kundenproblem. Für jede Anfrage speichert das System den Erhebungszeitpunkt und die API-Antwort. Nachdem ein Beispiel der Antwort geprüft wurde, können Felder normalisiert werden, die tatsächlich im JSON vorhanden sind, etwa eine Video-ID oder öffentliche Zähler, sofern sie enthalten sind.
Das Archiv beantwortet eine konkrete Frage: Welche Einträge lieferte die Suche nach dem gespeicherten Begriff während dieses Durchlaufs? Wenn die Antwort Kennzahlen enthält, können wiederholte Beobachtungen Unterschiede zwischen zu verschiedenen Zeitpunkten erfassten Werten zeigen. Ein solcher Unterschied bezieht sich auf die beobachteten Snapshots und den Zeitraum zwischen ihnen. Für einen Vergleich sollten beide Erhebungszeitpunkte und dasselbe Feld gespeichert werden.
Speichern Sie die Anfrage zusammen mit der Antwort. Die Zusammensetzung der Ergebnisse hängt vom konkreten Suchbegriff und Erhebungszeitpunkt ab. Das Archiv eignet sich daher zur Beobachtung der Ergebnisse für ausgewählte Anfragen, nicht als vollständiger Überblick über alle TikTok-Inhalte. IDs, ursprüngliche Antworten und Zeitstempel helfen dabei, die Herkunft jeder Zeile in einer späteren Tabelle nachzuprüfen.
Route und Parameter prüfen
Die Übersicht der TikTok-API-Routen nennt die Basis-URL https://tiktok.evelode.com und GET /searchVideo. Die aktuelle API-Spezifikation bezeichnet keyword als erforderlichen Suchparameter. Als optionale Parameter sind cursor, count, cache_timeout, date_posted, sort_by und region aufgeführt. Zur Autorisierung wird license_key übergeben. Angaben zur Route finden sich auch in der Dokumentation des Python-SDKs.
Mit den Parametern count und date_posted lassen sich Antwortumfang und Zeitraumfilter festlegen. Für sort_by sind die dokumentierten Werte most-liked, relevance oder date-posted zulässig. Wenn Sie die Paginierung verwenden, übergeben Sie den im vorherigen Antwortobjekt erhaltenen cursor als undurchsichtigen Wert, ohne ihn selbst zu berechnen. Für ein vergleichbares Tagesarchiv sollten Sie die Anfrageparameter und die Version Ihres eigenen Codes zusammen mit den Daten speichern.
Das folgende Beispiel verwendet für einen Testlauf einen kleinen Wert für count und die festgelegte Region US. Prüfen Sie vor der täglichen Erfassung eine einzelne Anfrage, ihren HTTP-Status und die JSON-Struktur. Die Antwort kann gefundene Videos unter tiktok.aweme_list oder unter tiktok.search_item_list enthalten, wobei sich das Videoobjekt in aweme_info befindet. Der Code unterstützt beide beobachteten Formen.
Projekt vorbereiten
Erstellen Sie eine virtuelle Umgebung und installieren Sie requests:
python -m venv .venv
source .venv/bin/activate
pip install requestsIn PowerShell aktivieren Sie die Umgebung mit dem Befehl .venv\Scripts\Activate.ps1. Legen Sie den Schlüssel und die Liste der Suchbegriffe über Umgebungsvariablen fest. Verwenden Sie für die TikTok-API den dokumentierten Variablennamen JSONSCRAPER_TIKTOK_LICENSE_KEY:
export JSONSCRAPER_TIKTOK_LICENSE_KEY="Ihr_Schlüssel"
export TIKTOK_QUERIES="Produktname,Produktkategorie,Kundenproblem"Snapshots erfassen und speichern
Das Beispiel sendet für jeden Suchbegriff eine Anfrage an die dokumentierte Route und speichert anschließend das ursprüngliche JSON, den Erhebungszeitpunkt und die verwendeten Parameter. Der Dateiname enthält das Datum und den Suchbegriff. Der Schlüssel bleibt in der Umgebung und wird nicht archiviert.
import json
import os
import re
import time
from datetime import datetime, timezone
from pathlib import Path
import requests
BASE_URL = "https://tiktok.evelode.com"
ENDPOINT = "/searchVideo"
LICENSE_KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
QUERIES = [
item.strip()
for item in os.environ["TIKTOK_QUERIES"].split(",")
if item.strip()
]
OUT = Path("data")
OUT.mkdir(exist_ok=True)
def safe_name(text):
cleaned = re.sub(r"[^a-zA-Z0-9_-]+", "_", text).strip("_")
return cleaned[:80] or "query"
def fetch(query):
params = {
"license_key": LICENSE_KEY,
"keyword": query,
"count": 10,
"region": "US",
}
response = requests.get(
BASE_URL + ENDPOINT,
params=params,
timeout=60,
)
response.raise_for_status()
payload = response.json()
if payload.get("status") != "ok":
raise RuntimeError("Die API hat einen anderen Status als ok zurückgegeben")
return payload
def extract_videos(payload):
tiktok = payload.get("tiktok") or {}
videos = list(tiktok.get("aweme_list") or [])
for item in tiktok.get("search_item_list") or []:
video = item.get("aweme_info") or {}
if video:
videos.append(video)
return videos
for query in QUERIES:
collected_at = datetime.now(timezone.utc).isoformat()
payload = fetch(query)
record = {
"collected_at": collected_at,
"query": query,
"request": {
"endpoint": ENDPOINT,
"keyword": query,
"count": 10,
"region": "US",
},
"videos_found": len(extract_videos(payload)),
"payload": payload,
}
filename = OUT / f"{collected_at[:10]}_{safe_name(query)}.json"
filename.write_text(
json.dumps(record, ensure_ascii=False, indent=2),
encoding="utf-8",
)
print(f"Antwort für Suchanfrage gespeichert: {query}")
time.sleep(1)
print(f"Gespeicherte Antworten: {len(QUERIES)}")Dieser minimale Collector sendet eine Anfrage pro Suchbegriff mit count=10. Für eine umfangreichere Erfassung können Sie die Paginierung über cursor ergänzen: Führen Sie weitere Anfragen aus und übergeben Sie den Cursorwert aus der Antwort, solange die API weitere Ergebnisse meldet. Speichern Sie jede Antwort separat. Cursor und Ergebnisanzahl bestimmen den jeweiligen Durchlauf; anhand des gespeicherten JSON lässt sich später prüfen, was jede Anfrage genau zurückgegeben hat.
Das Beispiel prüft den äußeren Wert status und liest anschließend das Objekt tiktok. Es sammelt Elemente aus aweme_list sowie aus search_item_list[].aweme_info, falls diese Form vorhanden ist. Zu den möglichen Feldern eines Videos gehören ID, Beschreibung, Autor, Link und Statistiken; einzelne Felder können fehlen. Speichern Sie deshalb die vollständige Antwort und prüfen Sie bei der Normalisierung, ob jedes Feld vorhanden ist.
Die Pause von einer Sekunde ist das Intervall zwischen den Anfragen des Skripts und keine Aussage über die Limits des Dienstes. Richten Sie Abfragehäufigkeit und Wiederholungsversuche anhand der Zugangsbedingungen und Dokumentation ein. Der Parameter cache_timeout ist für die Suche dokumentiert und legt die Cache-Dauer in Sekunden fest; laut Spezifikation deaktiviert der Wert 0 das Caching. Fügen Sie ihn hinzu, wenn dieses Verhalten zu Ihrem Anwendungsfall passt.
Normalisierung anhand der tatsächlichen Antwort ergänzen
Öffnen Sie nach dem ersten Durchlauf die gespeicherte Datei und prüfen Sie die Struktur von payload. Die Funktion extract_videos im Beispiel sammelt Elemente aus zwei dokumentierten Stellen, an denen Videoobjekte in der Antwort vorkommen können. Suchen Sie die genauen Schlüssel der Felder, die Sie analysieren möchten. Fehlt ein Feld in einem bestimmten Eintrag, speichern Sie es als fehlenden Wert, statt eine Zahl anzunehmen.
Für die weitere Verarbeitung können Sie eine Zeile pro gefundenem Objekt erstellen und collected_at sowie query hinzufügen. Bestätigte Felder lassen sich in einer CSV-Datei oder Datenbank speichern, während das ursprüngliche JSON im Archiv bleibt. So können Sie übersichtliche Tabellen erstellen und zugleich die Herkunft jedes Eintrags überprüfen.
Wenn die API eine Video-ID zurückgibt, verwenden Sie sie, um Beobachtungen desselben Videos aus verschiedenen Durchläufen miteinander zu verknüpfen. Speichern Sie jede Beobachtung separat, ohne frühere Daten zu überschreiben. Fehlt eine stabile ID, prüfen Sie zunächst, welche Attribute einen Abgleich ermöglichen, und gehen Sie nicht davon aus, dass eine Übereinstimmung anhand des Beschreibungstextes zuverlässig ist.
Snapshots vergleichen und Bericht erstellen
Gruppieren Sie die Einträge nach einem bestätigten Identifikator und sortieren Sie sie nach Erhebungszeitpunkt. Für Zählerfelder lässt sich die Differenz zwischen zwei aufeinanderfolgenden Werten mit gewöhnlichem Code berechnen. Ein Wechsel von 12.400 auf 18.900 bedeutet beispielsweise, dass sich der Zählerwert zwischen diesen Snapshots um 6.500 verändert hat. Geben Sie im Bericht die Beobachtungszeitpunkte und das ursprüngliche Feld an, damit die Lesenden die Berechnung prüfen können.
Eine nützliche Ergebnistabelle enthält den Suchbegriff, die ID des Beitrags, den Erhebungszeitpunkt und ausgewählte Felder aus der Antwort. Die Zusammenfassung kann nach Suchanfragen gruppiert und anhand eines bestätigten Zählers sortiert werden. So erhält das Team eine überprüfbare Liste der zurückgegebenen Einträge für die weitere Sichtung. Die Tabelle oder Nachricht sollten als separater Schritt erstellt werden, nachdem das tatsächliche Schema untersucht wurde.
Speichern Sie JSON-Dateien zunächst lokal. Sobald die Erfassung regelmäßig erfolgt, können Sie normalisierte Zeilen nach PostgreSQL oder in ein Analyse-Data-Warehouse übertragen und die ursprünglichen Antworten in einem Objektspeicher ablegen, wobei Datum und Anfrage im Dateinamen stehen. Das Original aufzubewahren ist besonders beim Anpassen des Parsers nützlich: Sie können ihn erneut auf historische Daten anwenden, ohne die API noch einmal abzufragen.
Erfassung nach Zeitplan ausführen
Rufen Sie das Skript für ein tägliches Archiv über cron oder einen anderen in Ihrer Umgebung verfügbaren Scheduler auf. Ein Job kann beispielsweise die Python-Datei einmal täglich ausführen und Schlüssel sowie Suchbegriffe über Umgebungsvariablen übergeben. Prüfen Sie vor dem regelmäßigen Einsatz zunächst eine Anfrage, dann die vollständige Begriffsliste und aktivieren Sie erst danach den Zeitplan.
Für einen zuverlässigen Betrieb sollten Sie den Status jeder Anfrage speichern, die Zahl der Wiederholungsversuche bei vorübergehenden Fehlern begrenzen und eine unvollständige Erfassung kennzeichnen, wenn ein Suchbegriff fehlschlägt. Geben Sie den Schlüssel nicht in Fehlermeldungen aus. Es ist außerdem sinnvoll, Dateien nach Datum und Anfragebezeichnung aufzuteilen, damit ein erneuter Durchlauf keinen vorherigen Snapshot überschreibt.
Wählen Sie die Häufigkeit nach Aufgabe und Anfragevolumen. Für einen täglichen Überblick genügt ein Durchlauf pro Tag; häufiger zu erfassen ist sinnvoll, wenn dem Team Änderungen im Tagesverlauf wichtig sind. Beginnen Sie mit einer kleinen Begriffsliste, prüfen Sie den Nutzen der zurückgegebenen Ergebnisse und erweitern Sie die Erfassung anschließend innerhalb der Zugangsbedingungen und Regeln zur Datennutzung.
KI für thematische Gruppierungen verwenden
Nachdem das Antwortschema bestätigt wurde, können ausgewählte Textfelder an ein Modell übergeben werden, damit es Beschreibungen vorab festgelegten Themen zuordnet oder einen knappen Entwurf für eine Zusammenfassung erstellt. Speichern Sie neben der Klassifizierung die ursprüngliche Beitrags-ID, den Suchbegriff und den Textausschnitt, auf dem die Kategorie beruht. So kann die Analyse vom Modellergebnis zum ursprünglichen Eintrag zurückverfolgt werden.
Numerische Differenzen, Sortierung und Deduplizierung sollten mit gewöhnlichem Code berechnet werden. Ein Modell eignet sich für die Verarbeitung von Text und für Formulierungen im Berichtsentwurf; Zähler und Zeitstempel stammen aus den gespeicherten Antworten. Durch diese Aufgabenteilung bleibt die Herkunft jeder Schlussfolgerung nachvollziehbar.
Prüfen Sie einen Teil der automatischen Kategorien manuell und speichern Sie Korrekturen als Testbeispiele. Wenn verschiedene Beitragstypen regelmäßig in derselben Gruppe landen, präzisieren Sie die Kategoriedefinitionen und wiederholen Sie die Prüfung. So lässt sich die Klassifizierungsqualität anhand der Daten Ihrer Aufgabe bewerten.
Fazit: ein wiederholbares Archiv und eine überprüfbare Zusammenfassung
Nach einer dokumentierten Anfrage mit dem Parameter keyword verfügt das Team über ein Archiv, aus dem hervorgeht, welche Suchbegriffe wann abgefragt wurden und welche Daten die API für jeden davon zurückgab. Darauf aufbauend lässt sich eine Ergebnistabelle erstellen, bestätigte Felder können zwischen Snapshots verglichen und eine Liste gefundener Beiträge zur manuellen Analyse vorbereitet werden.
Beginnen Sie mit einer Testanfrage und richten Sie anschließend die Begriffsliste und den Zeitplan ein. Die Beschreibung der TikTok Scraper API enthält die Basis-URL und die Routenübersicht; die Parameter von /searchVideo und das Antwortformat sind in der API-Spezifikation beschrieben. Das Archivieren geprüfter Antworten schafft eine Grundlage für wiederholbare Analysen mit festgelegten Suchbegriffen.