TikTokTikTok Search APITikTok Top Search APITikTok Foto-Karussell APIKeyword-Suche

TikTok Search API: Videos und Foto-Karussells finden

TikTok-Videos und Foto-Karussells mit SocQ recherchieren. Bildunterschriften, Creator, Medien und Interaktionszahlen erfassen, mit Filtern und Export-Code für JSON und CSV.

SocQAktualisiert am 16. Oktober 20267 Min. Lesezeit

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 query an POST /v1/tiktok/top-search. Lesen Sie nach erfolgreicher Aufgabe data.results.items. Verwenden Sie type=video für Videos und type=photo_carousel für Bildbeiträge; die Bildeinträge des Karussells stehen in media.

Den passenden Such-Endpunkt für Ihr Inhaltsformat wählen

AusgangspunktSocQ-EndpunktUmfang der Ergebnisse
Keyword, nur VideosTikTok SearchEin Workflow für die Videosuche
Keyword, Videos und BildbeiträgeTikTok Top SearchGemischte Ergebnisse, unterschieden über type
Bekannte Beitrags-URLTikTok VideosDen angegebenen Inhalt abrufen
Bekannte Sound-IDTikTok Song VideosVideos 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

ParameterZulässige Werte oder BereichBedeutung
queryErforderliches nicht leeres Keyword oder eine WortgruppeGesuchtes Thema
sort_byrelevance, date, likesGewünschte Sortierung der Ergebnisse; Standard ist Relevanz
published_withinday, week, month, three_months, six_monthsOptionaler Filter nach Veröffentlichungszeit
regionZweibuchstabiger Code, zum Beispiel USVerfügbarkeit der Inhalte für die Suche
results_limitGanze Zahlen von 1 bis 2.000; Standard 100Obergrenze ü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 FeldVideodatensatzDatensatz eines Foto-Karussells
id76785360685509706387685189869970246926
typevideophoto_carousel
author.usernamepatrickmcgee62coffeewithcandace
duration_seconds5.247null
MedieneinträgeEin VideoFü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