TikTokAPI de búsqueda de TikTokAPI de búsqueda principal de TikTokAPI de carruseles de fotos de TikTokBúsqueda por palabra clave

API de búsqueda de TikTok: encuentre videos y carruseles de fotos

Investigue videos y carruseles de fotos de TikTok con SocQ. Recopile descripciones, creadores, medios y conteos de interacción, con filtros y código de exportación a JSON y CSV.

SocQActualizado el 16 de octubre de 20268 min de lectura

Investigue videos y carruseles de fotos de TikTok en conjunto con SocQ. Recopile descripciones, creadores, enlaces a medios y conteos de interacción en torno a una palabra clave, y luego organice demostraciones en video, tarjetas de recetas y guías con imágenes en el mismo conjunto de datos temático.

La TikTok Top Search API de SocQ busca videos y carruseles de fotos públicos por palabra clave. Esta guía cubre la solicitud, el manejo de los formatos de resultado y las exportaciones de publicaciones y de enlaces ordenados de imágenes.

Respuesta rápida: Envíe un query obligatorio a POST /v1/tiktok/top-search. Cuando la tarea termine con éxito, lea data.results.items. Use type=video para videos y type=photo_carousel para publicaciones de imágenes; las imágenes del carrusel están en media.

Elegir el endpoint de búsqueda según el formato de contenido

Punto de partidaEndpoint de SocQAlcance de los resultados
Palabra clave, solo videosTikTok SearchUn flujo de búsqueda de videos
Palabra clave, videos y publicaciones de imágenesTikTok Top SearchResultados mixtos diferenciados por type
URL de publicación conocidaTikTok VideosObtener el contenido especificado
ID de sonido conocidoTikTok Song VideosEncontrar los videos asociados con ese sonido

Top Search devuelve las publicaciones existentes para una palabra clave. Para trabajar con publicaciones de fotos, seleccione type=photo_carousel en los resultados y lea las imágenes en media.

Buscar en TikTok por palabra clave

Defina SOCQ_API_KEY y envíe una búsqueda limitada a 20 registros:

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}'

Guarde data.task_id como TASK_ID y consulte esa tarea:

curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=100" \
  -H "Authorization: Bearer $SOCQ_API_KEY"

Espere entre consultas mientras el estado sea queued, running o retrying. En succeeded, lea data.results.items; en failed, revise data.error_message. Si el resultado tiene has_more=true, siga next_cursor para leer las páginas guardadas restantes.

El cursor de resultados de una tarea lee registros guardados. El results_limit enviado define el tope de la recopilación. Tras un tiempo de espera agotado del cliente, reanude la consulta con el ID de la tarea existente.

Definir el orden, los filtros de publicación y la región

ParámetroValores o rango aceptadosSignificado
queryPalabra clave o frase obligatoria y no vacíaTema que se va a buscar
sort_byrelevance, date, likesOrden solicitado de los resultados; el valor predeterminado es relevance
published_withinday, week, month, three_months, six_monthsFiltro opcional por tiempo de publicación
regionCódigo de dos letras, como USDisponibilidad del contenido para la búsqueda
results_limitEnteros de 1 a 2000; valor predeterminado 100Tope entre los formatos de contenido devueltos

day selecciona ayer, week esta semana y month este mes. Estas tres opciones usan períodos calendario. three_months y six_months seleccionan los últimos tres y seis meses, respectivamente.

region cambia qué contenido es accesible para la búsqueda. Guarde region=US como una condición de la solicitud; verifique la ubicación del creador con evidencia geográfica independiente.

Por ejemplo, si 20 resultados incluyen ocho carruseles de fotos, el filtrado por formato produce ocho publicaciones de fotos. results_limit cuenta ambos formatos en conjunto, y la cantidad de fotos depende de su distribución en esa captura.

Leer los resultados de videos y de carruseles de fotos

Los siguientes ejemplos de un video y de un carrusel de cinco imágenes muestran cómo leer cada formato de resultado:

Campo observadoRegistro de videoRegistro de carrusel de fotos
id76785360685509706387685189869970246926
typevideophoto_carousel
author.usernamepatrickmcgee62coffeewithcandace
duration_seconds5.247null
Entradas de mediosUn videoCinco imágenes

Los registros estándar almacenan las descripciones en text, los medios en media, la información del sonido en audio y los conteos de interacción en metrics. Procese las consultas posteriores con los registros devueltos por sus propias tareas.

Lea las imágenes del carrusel en el orden de medios devuelto. Un duration_seconds null significa que no se proporcionó duración; una métrica null significa que no se proporcionó medición. Conserve los ceros devueltos y mantenga los conteos de reproducciones y de vistas en sus campos respectivos.

Exportar resultados de búsqueda e imágenes de carruseles con Python

Guarde este asistente de biblioteca estándar como 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")

Guarde lo siguiente como export_search.py en el mismo directorio:

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

El JSON conserva todos los registros recopilados. El CSV de publicaciones elimina duplicados por ID, mientras que el CSV de imágenes guarda los IDs de las publicaciones y las posiciones de los medios para reconstruir el orden del carrusel. Los registros sin ID se conservan por separado; confirme sus publicaciones de origen antes de unirlos con otros conjuntos de datos.

Conserve tanto las URL de las publicaciones como las de los medios para abrir la publicación de origen y acceder a sus medios. Conserve los valores vacíos cuando falten direcciones de imágenes. El CSV escapa el texto público con apariencia de fórmula; importe los IDs de las publicaciones como texto para conservar todos los dígitos.

Convertir las publicaciones recopiladas en una revisión temática

Para una revisión de recetas de café, clasifique las publicaciones recopiladas como tarjetas de imágenes o demostraciones en video. Lea tanto las descripciones como los medios al asignar los temas. Extraer el texto completo que aparece dentro de las imágenes requiere un paso aparte de reconocimiento de texto.

Conserve la consulta, los filtros y la hora de captura con cada comparación. Etiquete un orden local por Me gusta como “clasificación por Me gusta dentro de esta muestra” e informe el tamaño de la muestra y el alcance de la recopilación junto con ella.

Para un descubrimiento guiado por el audio, consulte el tutorial de listas de música de TikTok. Para los flujos de perfiles, videos conocidos y comentarios, use la guía de scraping de TikTok.

Cree un único conjunto de datos de investigación para videos e imágenes

SocQ Top Search usa un único flujo de solicitud para videos y carruseles de fotos, con campos estándar para identificar cada formato. El código de exportación crea tanto una tabla de publicaciones como una tabla ordenada de imágenes, y así su biblioteca temática o su interfaz de revisión cuentan con los enlaces de origen y las posiciones de las diapositivas que necesitan.

Abra Top Search y pruebe su palabra clave.

Preguntas frecuentes (FAQ)

¿La API de búsqueda de TikTok puede devolver carruseles de fotos?

Top Search devuelve videos y carruseles de fotos, diferenciados por type, con los medios en media. El endpoint TikTok Search, que es independiente, sirve para la búsqueda de videos.

¿Puedo buscar solo fotos de TikTok?

Recopile los resultados y luego seleccione type=photo_carousel. El filtrado de fotos se hace en su aplicación; el tope de la recopilación cuenta ambos formatos.

¿Top Search devuelve las palabras clave más buscadas o los volúmenes de búsqueda?

Top Search recibe su palabra clave y devuelve registros de publicaciones. Los volúmenes de búsqueda de palabras clave y las listas de consultas en tendencia son tipos de datos distintos y no se incluyen en esta respuesta.

¿La región identifica dónde vive el creador?

region ajusta la disponibilidad del contenido para la búsqueda. Verifique por separado la residencia del creador o la ubicación de la publicación.

¿Puedo obtener todas las publicaciones que coinciden con una palabra clave?

El endpoint devuelve las publicaciones seleccionadas por esa búsqueda, hasta results_limit. Leer todas las páginas de resultados recupera el conjunto completo de resultados guardados de la tarea; su cobertura temática la definen esos registros.

¿Por qué una publicación de fotos no tiene duración ni conteo de reproducciones?

Lea los carruseles de fotos como entradas de imágenes. Conserve null cuando falte la duración o la medición de reproducciones, y conserve 0 cuando la fuente devuelva cero.

¿Puedo publicar un carrusel con esta API?

Top Search recupera contenido público existente. La publicación de carruseles usa un flujo de publicación aparte. Consulte la página de la Top Search API para ver las entradas, los campos y la facturación de este endpoint.

TIKTOK API

Probar el flujo de trabajo con una URL pública de TikTok

Envíe entradas públicas y reciba registros normalizados con contexto de origen rastreable.

Ver las API de TikTok