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
queryobligatorio aPOST /v1/tiktok/top-search. Cuando la tarea termine con éxito, leadata.results.items. Usetype=videopara videos ytype=photo_carouselpara publicaciones de imágenes; las imágenes del carrusel están enmedia.
Elegir el endpoint de búsqueda según el formato de contenido
| Punto de partida | Endpoint de SocQ | Alcance de los resultados |
|---|---|---|
| Palabra clave, solo videos | TikTok Search | Un flujo de búsqueda de videos |
| Palabra clave, videos y publicaciones de imágenes | TikTok Top Search | Resultados mixtos diferenciados por type |
| URL de publicación conocida | TikTok Videos | Obtener el contenido especificado |
| ID de sonido conocido | TikTok Song Videos | Encontrar 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ámetro | Valores o rango aceptados | Significado |
|---|---|---|
query | Palabra clave o frase obligatoria y no vacía | Tema que se va a buscar |
sort_by | relevance, date, likes | Orden solicitado de los resultados; el valor predeterminado es relevance |
published_within | day, week, month, three_months, six_months | Filtro opcional por tiempo de publicación |
region | Código de dos letras, como US | Disponibilidad del contenido para la búsqueda |
results_limit | Enteros de 1 a 2000; valor predeterminado 100 | Tope 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 observado | Registro de video | Registro de carrusel de fotos |
|---|---|---|
id | 7678536068550970638 | 7685189869970246926 |
type | video | photo_carousel |
author.username | patrickmcgee62 | coffeewithcandace |
duration_seconds | 5.247 | null |
| Entradas de medios | Un video | Cinco 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