Michael JohnsonTras lanzar una aplicación o una nueva función, los comentarios se dispersan rápidamente entre vídeos cortos. Un especialista en marketing encuentra algunos vídeos manualmente y comparte los enlaces en un chat; más tarde, el analista no puede saber qué publicaciones ya se habían tenido en cuenta ni cómo cambiaron las visualizaciones. Una solución práctica consiste en recopilar periódicamente los resultados de búsqueda con varias consultas estables, guardar las respuestas originales y elaborar informes a partir de campos confirmados.
En esta guía configuraremos este tipo de recopilación para un caso concreto: un equipo ha lanzado una nueva función y quiere seguir semanalmente los vídeos públicos de TikTok cuya descripción incluya el nombre del producto, una función clave o un problema habitual de los usuarios. Se trata de supervisar una muestra de resultados de búsqueda: la API devuelve resultados según la consulta y los parámetros, no una lista garantizada de todas las publicaciones sobre el lanzamiento.
Primero, define qué señales necesita el equipo
Un gran número de visualizaciones, por sí solo, no explica bien qué conviene hacer a continuación. Al equipo le resulta más útil saber qué preguntas se repiten, qué casos de uso muestra la gente y qué vídeos reciben reacciones públicas destacadas. Por eso, primero formula varias búsquedas y decide qué campos incluirás en el informe.
Por ejemplo, para el lanzamiento de una herramienta de planificación de publicaciones, puedes probar las consultas «nombre del producto», «planificador de contenido» y «cómo programar una publicación en TikTok». Las frases deben reflejar distintas formas en que la gente puede describir un mismo tema. Anótalas junto con la fecha de inicio del seguimiento y la región, de modo que puedas comparar las recopilaciones posteriores con la misma configuración.
Una tabla mínima puede incluir la hora de recopilación, la consulta, el identificador del vídeo, el enlace, la descripción, el nombre del autor, el identificador del autor y los valores disponibles de visualizaciones, «me gusta» y comentarios. TikTok Scraper API documenta campos como aweme_id, desc, share_url, información del autor y algunas estadísticas para los resultados de búsqueda. Comprueba cada campo en cada objeto concreto: puede que algunas métricas no estén disponibles.
Conecta la búsqueda documentada
Para buscar vídeos, utiliza la ruta GET /searchVideo en la dirección base https://tiktok.evelode.com. La documentación enumera el parámetro obligatorio keyword y los parámetros opcionales count, cursor, date_posted, sort_by, region y cache_timeout. Entre los valores admitidos para el filtro de fecha está this-week; para la ordenación, relevance, most-liked y date-posted. Consulta la referencia de rutas de TikTok API para verificar su función y sus nombres.
La clave de licencia se envía como parámetro de consulta license_key. En un script de producción, léela de la variable de entorno JSONSCRAPER_TIKTOK_LICENSE_KEY; no incluyas el secreto en el código fuente ni lo escribas en los registros. Este ejemplo está pensado para Python 3.8 o posterior y utiliza el paquete requests:
import os
import requests
BASE_URL = "https://tiktok.evelode.com"
API_KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
def search_videos(keyword, cursor=None):
params = {
"license_key": API_KEY,
"keyword": keyword,
"count": 20,
"date_posted": "this-week",
"sort_by": "date-posted",
"region": "US",
}
if cursor is not None:
params["cursor"] = cursor
response = requests.get(
f"{BASE_URL}/searchVideo",
params=params,
timeout=30,
)
response.raise_for_status()
payload = response.json()
if payload.get("status") != "ok":
raise RuntimeError("TikTok API devolvió un estado distinto de ok")
return payload["tiktok"]
result = search_videos("content planning app")
print("Objetos encontrados:", len(result.get("aweme_list", [])))El script comprueba los errores HTTP y el estado externo de la respuesta. Una respuesta HTTP satisfactoria no garantiza por sí sola que la búsqueda contenga vídeos: si la muestra está vacía, la lista puede no tener elementos. En la primera ejecución, conviene guardar la respuesta completa en un almacenamiento protegido para poder comparar los objetos reales con la tabla de campos normalizados.
Procesa los dos formatos de respuesta de búsqueda
La estructura de los resultados de búsqueda tiene una particularidad importante. Los vídeos pueden encontrarse directamente en tiktok.aweme_list o dentro de tiktok.search_item_list[].aweme_info. Si el procesador solo lee la primera lista, podría omitir resultados que aparecen en el segundo formato.
Añade un pequeño normalizador que admita ambas estructuras y omita sin problemas los elementos que no incluyan el objeto de vídeo anidado:
def extract_awemes(tiktok):
items = list(tiktok.get("aweme_list") or [])
for item in tiktok.get("search_item_list") or []:
aweme = item.get("aweme_info")
if aweme:
items.append(aweme)
return items
def normalize(aweme, keyword, collected_at):
author = aweme.get("author") or {}
stats = aweme.get("statistics") or {}
return {
"collected_at": collected_at,
"keyword": keyword,
"video_id": aweme.get("aweme_id"),
"posted_at": aweme.get("create_time"),
"description": aweme.get("desc"),
"share_url": aweme.get("share_url"),
"author_id": author.get("uid"),
"author_name": author.get("nickname"),
"views": stats.get("play_count"),
"likes": stats.get("digg_count"),
"comments": stats.get("comment_count"),
"shares": stats.get("share_count"),
}Los valores ausentes se mantienen como None. No los sustituyas por cero: cero significa que se midió ese valor, mientras que None conserva el hecho de que el campo no venía en la respuesta. Esta diferencia influye en los promedios, las proporciones y cualquier conclusión del equipo.
Guarda el historial, no solo la instantánea actual
Para observar la evolución, almacena registros de observaciones independientes. El identificador del vídeo permite deduplicar publicaciones, pero no eliminar el historial: si el mismo vídeo vuelve a aparecer en la siguiente recopilación, se obtiene un nuevo punto de observación. Por ejemplo, puedes crear una clave única para la tabla de observaciones con video_id y collected_at, y guardar el enlace y la descripción en el registro para facilitar su comprobación.
Un esquema mínimo en SQLite resulta útil para un prototipo:
import sqlite3
conn = sqlite3.connect("tiktok_observations.sqlite3")
conn.execute("""
CREATE TABLE IF NOT EXISTS observations (
video_id TEXT NOT NULL,
collected_at TEXT NOT NULL,
keyword TEXT NOT NULL,
posted_at INTEGER,
description TEXT,
share_url TEXT,
author_id TEXT,
author_name TEXT,
views INTEGER,
likes INTEGER,
comments INTEGER,
shares INTEGER,
PRIMARY KEY (video_id, collected_at, keyword)
)
""")
conn.commit()En la práctica, normaliza la hora de recopilación a UTC, guarda el JSON original por separado y añade una columna con la versión del esquema. La respuesta original ayuda a revisar la transformación cuando la estructura de los nuevos objetos difiere de la habitual. Si una publicación aparece con varias consultas, guarda las frases coincidentes en una tabla relacionada o combínalas al generar el informe.
Paginación: continúa solo con el cursor de la respuesta
El parámetro cursor permite continuar la búsqueda. Su valor se obtiene de la respuesta anterior y se vuelve a enviar sin transformarlo; el proceso termina cuando has_more ya no indica que haya más resultados o cuando se alcanza el límite establecido. Trata el cursor como un valor opaco: no lo calcules por tu cuenta ni lo sustituyas por un contador de páginas.
def collect_pages(keyword, max_pages=3):
cursor = None
collected = []
for _ in range(max_pages):
page = search_videos(keyword, cursor)
collected.extend(extract_awemes(page))
if not page.get("has_more"):
break
cursor = page.get("cursor")
if cursor is None:
break
return collectedLimitar el número de páginas hace que la tarea periódica tenga un volumen de solicitudes predecible. Registra el número de páginas y el valor de has_more en el registro de ejecución: esto aporta contexto al informe sobre la muestra. Incluso con paginación, el resultado describe las respuestas recibidas de la API y el límite de recopilación establecido; no es una estimación de todas las publicaciones de la plataforma.
Elabora un informe reproducible
Programa la recopilación semanalmente o con mayor frecuencia si el equipo necesita señales más frecuentes. En cada ejecución, registra la lista de consultas, los parámetros, la hora, el número de objetos recibidos y el número de identificadores únicos. Cuenta por separado las publicaciones detectadas por primera vez en esa ejecución y las que ya habían aparecido.
El informe puede incluir cuatro vistas sencillas:
- Vídeos nuevos: enlaces, descripciones, fecha de publicación y consulta con la que se encontró cada vídeo.
- Temas recurrentes: agrupación de las descripciones en categorías definidas manualmente, por ejemplo, «error de configuración», «solicitud de función» y «descripción de un caso de uso».
- Reacciones públicas: visualizaciones, «me gusta», comentarios y compartidos disponibles, mostrados junto a la hora de observación.
- Señales para revisar: nuevas formas de expresarse, preguntas frecuentes o vídeos que un miembro del equipo debería analizar.
No describas la diferencia entre dos instantáneas como «nuevos me gusta» sin verificar la semántica y la actualidad de los valores de la respuesta. Es más preciso decir «valor de la métrica en la última respuesta recibida» y «diferencia entre las instantáneas guardadas». Así, el equipo sabe qué se ha calculado exactamente y puede abrir la publicación original antes de tomar una decisión.
Usa la IA para clasificar, no para sustituir la recopilación
Tras normalizar los datos, puedes enviar las descripciones de los vídeos a un modelo para que las clasifique en categorías predefinidas. Envía solo los campos de texto necesarios y pídele un resultado estructurado: categoría, motivo breve, nivel de confianza y fragmento de la descripción en el que se basa la etiqueta. Conserva la publicación original junto a la etiqueta para que un analista pueda revisar los casos dudosos.
El flujo de trabajo sigue siendo sencillo: un planificador inicia la recopilación; Python valida la respuesta y guarda el JSON; otra tarea normaliza los registros nuevos; un clasificador procesa solo las descripciones nuevas; y el informe se genera a partir de la base de datos y se envía al canal elegido por el equipo. TikTok Scraper API proporciona los datos de búsqueda; la clasificación y el envío del informe forman parte de la lógica de integración, que puedes implementar en Python, n8n o Make.
Para reducir el ruido, define un vocabulario de categorías antes de enviar los datos al modelo y revisa periódicamente una muestra etiquetada manualmente. Para descripciones breves o ambiguas, es preferible usar el estado «contexto insuficiente» a forzar una categoría. Las etiquetas de IA ayudan a organizar la cola de revisión, pero las conclusiones sobre problemas de los usuarios deben confirmarse leyendo las publicaciones y comparando varias observaciones.
Errores, reintentos y manejo seguro de la clave
Una solicitud de red puede terminar por tiempo de espera agotado, un error temporal o una respuesta que no se pueda interpretar como JSON. Divide el procesamiento en etapas: solicitud, comprobación del código HTTP, análisis del JSON, validación del estado externo, normalización y almacenamiento. Ante errores temporales, utiliza un número limitado de reintentos con pausas cada vez más largas; registra los errores persistentes para analizarlos después, sin marcar la ejecución como satisfactoria.
Guarda la clave en el gestor de secretos del entorno de ejecución o en una variable de entorno. Como la API recibe license_key en la cadena de consulta, evita registrar la URL completa y los parámetros de la solicitud: contendrían el secreto. Para diagnosticar problemas, registra la ruta, el código de respuesta, la duración, la consulta y el identificador de la tarea, pero elimina la clave de los registros.
Establece la frecuencia y el volumen de la muestra según tu caso de uso y las condiciones de uso de la plataforma. Conviene limitar la recopilación de datos públicos a lo que realmente se necesita para el análisis; las normas internas del equipo deben especificar cómo se almacenan las descripciones, los enlaces y los identificadores de autor. Las respuestas de la API y sus métricas pueden ser incompletas o cambiar entre observaciones, por lo que el informe debe conservar la hora de recopilación y el origen de cada fila.
Resultado: del intercambio manual de enlaces a un historial verificable
Una vez configurado el proceso, el equipo recibe una lista actualizada periódicamente de los vídeos encontrados, las respuestas originales para auditoría, una tabla de métricas públicas disponibles y un resumen de temas recurrentes. Esto ayuda a detectar antes las preguntas sobre una nueva función, encontrar ejemplos de casos de uso y elegir publicaciones para analizarlas manualmente. La comparación de instantáneas muestra cómo cambian los valores guardados de los vídeos ya encontrados, mientras que el registro de consultas explica cómo se formó la muestra.
Empieza con una sola consulta y un límite pequeño de páginas, comprueba la estructura real de la respuesta y, después, añade más formulaciones y una programación. Antes de pasar el prototipo a producción, establece reglas de deduplicación, almacenamiento y gestión de errores. Las rutas y los parámetros actuales están disponibles en la documentación oficial de la API; la página de TikTok Scraper API describe sus funciones y permite empezar a probarla.
