Recherchieren Sie TikTok-Videos und Foto-Karussells gemeinsam mit SocQ. Erfassen Sie zu einem Keyword Bildunterschriften, Creator, Medienlinks und Interaktionszahlen und ordnen Sie dann Videodemonstrationen, Rezeptkarten und Bildanleitungen im selben Themen-Datensatz.
Die SocQ TikTok Top Search API durchsucht öffentliche Videos und Foto-Karussells per Keyword. Dieser Leitfaden behandelt die Anfrage, den Umgang mit dem Ergebnisformat und Exporte von Beiträgen und geordneten Bildlinks.
Kurzantwort: Senden Sie die erforderliche
queryanPOST /v1/tiktok/top-search. Lesen Sie nach erfolgreicher Aufgabedata.results.items. Verwenden Sietype=videofür Videos undtype=photo_carouselfür Bildbeiträge; die Bildeinträge des Karussells stehen inmedia.
Den passenden Such-Endpunkt für Ihr Inhaltsformat wählen
| Ausgangspunkt | SocQ-Endpunkt | Umfang der Ergebnisse |
|---|---|---|
| Keyword, nur Videos | TikTok Search | Ein Workflow für die Videosuche |
| Keyword, Videos und Bildbeiträge | TikTok Top Search | Gemischte Ergebnisse, unterschieden über type |
| Bekannte Beitrags-URL | TikTok Videos | Den angegebenen Inhalt abrufen |
| Bekannte Sound-ID | TikTok Song Videos | Videos finden, die mit diesem Sound verbunden sind |
Top Search liefert vorhandene Beiträge zu einem Keyword. Wenn Sie mit Fotobeiträgen arbeiten möchten, wählen Sie aus den Ergebnissen type=photo_carousel aus und lesen die Bilder in media.
TikTok per Keyword durchsuchen
Setzen Sie SOCQ_API_KEY und senden Sie eine Suche, die auf 20 Datensätze begrenzt ist:
curl -X POST "https://api.socq.ai/v1/tiktok/top-search" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"coffee","sort_by":"relevance","results_limit":20}'
Speichern Sie data.task_id als TASK_ID und fragen Sie diese Aufgabe ab:
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=100" \
-H "Authorization: Bearer $SOCQ_API_KEY"
Warten Sie zwischen den Abfragen, solange der Status queued, running oder retrying lautet. Lesen Sie bei succeeded die Daten unter data.results.items; prüfen Sie bei failed den Wert data.error_message. Hat das Ergebnis has_more=true, folgen Sie next_cursor, um die übrigen gespeicherten Seiten zu lesen.
Ein Cursor im Aufgabenergebnis liest gespeicherte Datensätze. Das übermittelte results_limit legt die Obergrenze der Erfassung fest. Setzen Sie nach einer Zeitüberschreitung des Clients die Abfrage mit der bestehenden Aufgaben-ID fort.
Sortierung, Veröffentlichungsfilter und Region festlegen
| Parameter | Zulässige Werte oder Bereich | Bedeutung |
|---|---|---|
query | Erforderliches nicht leeres Keyword oder eine Wortgruppe | Gesuchtes Thema |
sort_by | relevance, date, likes | Gewünschte Sortierung der Ergebnisse; Standard ist Relevanz |
published_within | day, week, month, three_months, six_months | Optionaler Filter nach Veröffentlichungszeit |
region | Zweibuchstabiger Code, zum Beispiel US | Verfügbarkeit der Inhalte für die Suche |
results_limit | Ganze Zahlen von 1 bis 2.000; Standard 100 | Obergrenze über alle zurückgegebenen Inhaltsformate |
day wählt gestern, week diese Woche und month diesen Monat. Diese drei Optionen verwenden Kalenderzeiträume. three_months und six_months wählen die letzten drei beziehungsweise sechs Monate.
region ändert, welche Inhalte für die Suche zugänglich sind. Speichern Sie region=US als Bedingung der Anfrage; prüfen Sie den Standort eines Creators anhand separater geografischer Belege.
Ein Beispiel: Wenn unter 20 Ergebnissen acht Foto-Karussells sind, ergibt das Filtern nach Format acht Fotobeiträge. results_limit zählt beide Formate zusammen, und die Zahl der Fotos hängt von deren Verteilung in dieser Erfassung ab.
Ergebnisse von Videos und Foto-Karussells lesen
Die folgenden Beispiele für ein Video und ein Karussell mit fünf Bildern zeigen, wie sich jedes Ergebnisformat lesen lässt:
| Beobachtetes Feld | Videodatensatz | Datensatz eines Foto-Karussells |
|---|---|---|
id | 7678536068550970638 | 7685189869970246926 |
type | video | photo_carousel |
author.username | patrickmcgee62 | coffeewithcandace |
duration_seconds | 5.247 | null |
| Medieneinträge | Ein Video | Fünf Bilder |
Standard-Datensätze speichern Bildunterschriften in text, Medien in media, Sound-Informationen in audio und Interaktionszahlen in metrics. Verarbeiten Sie nachfolgende Abfragen mit den Datensätzen, die ihre eigenen Aufgaben zurückgeben.
Lesen Sie die Bilder eines Karussells in der zurückgegebenen Reihenfolge der Medien. Ein duration_seconds mit dem Wert null bedeutet, dass keine Dauer geliefert wurde; eine Kennzahl mit dem Wert null bedeutet, dass kein Messwert geliefert wurde. Behalten Sie zurückgegebene Nullen bei und führen Sie Wiedergaben und Aufrufe in ihren jeweiligen Feldern getrennt.
Suchergebnisse und Karussell-Bilder mit Python exportieren
Speichern Sie diesen Helfer aus der Standardbibliothek als socq_collect.py:
import json
import os
import time
from urllib.parse import urlencode
from urllib.request import Request, urlopen
BASE = "https://api.socq.ai/v1"
PENDING = {"queued", "running", "retrying"}
def api(method, path, payload=None):
body = json.dumps(payload).encode("utf-8") if payload is not None else None
request = Request(
BASE + path, data=body, method=method,
headers={
"Authorization": "Bearer " + os.environ["SOCQ_API_KEY"],
"Content-Type": "application/json",
},
)
with urlopen(request, timeout=60) as response:
result = json.load(response)
if result.get("code") != 200:
raise RuntimeError(result)
return result["data"]
def collect(endpoint, payload):
task_id = api("POST", "/" + endpoint, payload)["task_id"]
print("Task:", task_id, flush=True)
path = "/tasks/" + task_id
deadline = time.monotonic() + 600
data = api("GET", path + "?limit=100")
while data["status"] in PENDING:
if time.monotonic() >= deadline:
raise TimeoutError("Resume GET " + path + "; do not resubmit automatically")
time.sleep(2)
data = api("GET", path + "?limit=100")
if data["status"] != "succeeded":
raise RuntimeError(data.get("error_message") or data["status"])
items, seen_cursors = [], set()
while True:
if time.monotonic() >= deadline:
raise TimeoutError("Resume pagination for " + task_id)
page = data["results"]
items.extend(page["items"])
if not page["has_more"]:
return task_id, items
cursor = page.get("next_cursor")
if not cursor or cursor in seen_cursors:
raise RuntimeError("Missing or repeated result cursor")
seen_cursors.add(cursor)
data = api("GET", path + "?" + urlencode({"limit": 100, "cursor": cursor}))
if data["status"] != "succeeded":
raise RuntimeError("Task is not ready for result pagination")
Speichern Sie Folgendes als export_search.py im selben Verzeichnis:
import csv
import json
from socq_collect import collect
payload = {"query": "coffee", "sort_by": "relevance", "results_limit": 20}
task_id, records = collect("tiktok/top-search", payload)
with open("tiktok-search.json", "w", encoding="utf-8") as f:
json.dump({"task_id": task_id, "input": payload, "items": records},
f, ensure_ascii=False, indent=2)
def csv_cell(value):
if value is None:
return ""
if isinstance(value, str) and value.lstrip().startswith(("=", "+", "-", "@")):
return "'" + value
return value
def write_csv(path, fields, rows):
with open(path, "w", encoding="utf-8-sig", newline="") as f:
writer = csv.DictWriter(f, fieldnames=fields)
writer.writeheader()
writer.writerows({k: csv_cell(v) for k, v in row.items()} for row in rows)
posts, images, seen_ids = [], [], set()
for item in records:
post_id = item.get("id")
if post_id is not None:
if str(post_id) in seen_ids:
continue
seen_ids.add(str(post_id))
metrics = item.get("metrics") or {}
posts.append({"post_id": post_id, "type": item.get("type"),
"text": item.get("text"), "url": item.get("url"),
"username": (item.get("author") or {}).get("username"),
"published_at": item.get("published_at"),
"likes_count": metrics.get("likes_count"),
"views_count": metrics.get("views_count"),
"collected_at": item.get("collected_at")})
if item.get("type") == "photo_carousel":
for position, media in enumerate(item.get("media") or [], start=1):
if media.get("type") == "image":
images.append({"post_id": post_id, "media_position": position,
"image_url": media.get("url"),
"width": media.get("width"), "height": media.get("height")})
write_csv("tiktok-search.csv", ["post_id", "type", "text", "url", "username",
"published_at", "likes_count", "views_count", "collected_at"], posts)
write_csv("tiktok-carousel-images.csv", ["post_id", "media_position", "image_url",
"width", "height"], images)
python3 export_search.py
Das JSON bewahrt alle erfassten Datensätze. Die CSV-Datei der Beiträge dedupliziert Beiträge nach ID, während die CSV-Datei der Bilder Beitrags-IDs und Medienpositionen speichert, um die Reihenfolge des Karussells wiederherzustellen. Datensätze ohne ID werden separat beibehalten; prüfen Sie deren Quellbeiträge, bevor Sie sie mit anderen Datensätzen verknüpfen.
Behalten Sie sowohl Beitrags-URLs als auch Medien-URLs, um den Quellbeitrag zu öffnen und auf seine Medien zuzugreifen. Lassen Sie Felder mit fehlenden Bildadressen leer. Die CSV-Datei maskiert öffentlichen Text, der wie eine Formel aussieht; importieren Sie Beitrags-IDs als Text, damit jede Ziffer erhalten bleibt.
Die erfassten Beiträge zu einer Themenauswertung machen
Ordnen Sie für eine Auswertung zu Kaffeerezepten die erfassten Beiträge als Bildkarten oder Videodemonstrationen ein. Lesen Sie bei der Themenzuordnung sowohl Bildunterschriften als auch Medien. Den vollständigen Text, der in Bildern zu sehen ist, extrahieren Sie in einem separaten Schritt zur Texterkennung.
Halten Sie bei jedem Vergleich Suchanfrage, Filter und Erfassungszeit fest. Kennzeichnen Sie eine lokale Sortierung nach Likes als „Likes-Ranking innerhalb dieser Stichprobe“ und nennen Sie dazu Stichprobengröße und Umfang der Erfassung.
Für Discovery über Audio siehe die Anleitung zu den TikTok-Musikcharts. Für Workflows zu Profilen, bekannten Videos und Kommentaren nutzen Sie die TikTok-Scraping-Anleitung.
Einen Recherche-Datensatz für Videos und Bilder aufbauen
SocQ Top Search verwendet für Videos und Foto-Karussells einen gemeinsamen Anfrage-Workflow mit Standardfeldern, die jedes Format kennzeichnen. Der Export-Code erzeugt sowohl eine Tabelle der Beiträge als auch eine geordnete Tabelle der Bilder und liefert Ihrer Themenbibliothek oder Prüfoberfläche die Quelllinks und Folienpositionen, die sie braucht.
Top Search öffnen und Ihr Keyword ausprobieren.
Häufig gestellte Fragen (FAQ)
Kann die TikTok Search API Foto-Karussells zurückgeben?
Top Search liefert Videos und Foto-Karussells, unterschieden über type, mit den Medien in media. Der separate Endpunkt TikTok Search ist für die Videosuche gedacht.
Kann ich nur nach TikTok-Fotos suchen?
Erfassen Sie die Ergebnisse und wählen Sie dann type=photo_carousel aus. Das Filtern nach Fotos erfolgt in Ihrer Anwendung; die Obergrenze der Erfassung zählt beide Formate.
Liefert Top Search beliebte Suchbegriffe oder Suchvolumen?
Top Search nimmt Ihr Keyword entgegen und liefert Beitragsdatensätze. Suchvolumen zu Keywords und Listen von Trend-Suchanfragen sind eigene Datentypen und in dieser Antwort nicht enthalten.
Gibt die Region an, wo der Creator lebt?
region passt die Verfügbarkeit der Inhalte für die Suche an. Prüfen Sie den Wohnort des Creators oder den Standort des Beitrags separat.
Kann ich jeden Beitrag erhalten, der zu einem Keyword passt?
Der Endpunkt liefert die Beiträge, die diese Suche auswählt, bis zu results_limit. Wer jede Ergebnisseite liest, ruft den vollständigen gespeicherten Ergebnissatz der Aufgabe ab; die thematische Abdeckung ergibt sich aus diesen Datensätzen.
Warum hat ein Fotobeitrag weder Dauer noch Wiedergabezahl?
Lesen Sie Foto-Karussells als Bildeinträge. Behalten Sie null bei fehlender Dauer oder fehlenden Wiedergaben bei, und behalten Sie 0 bei, wenn die Quelle null liefert.
Kann ich mit dieser API ein Karussell veröffentlichen?
Top Search ruft vorhandene öffentliche Inhalte ab. Das Veröffentlichen von Karussells nutzt einen separaten Workflow zum Posten. Eingaben, Felder und Abrechnung dieses Endpunkts finden Sie auf der Seite zur Top Search API.
TIKTOK API
Workflow mit einer öffentlichen TikTok-URL testen
Senden Sie öffentliche Eingaben und erhalten Sie normalisierte Datensätze mit nachvollziehbarem Quellkontext.
TikTok-APIs ansehen