Un informe semanal de búsquedas en TikTok resulta útil cuando muestra qué vídeos aparecieron en la nueva consulta desde la ejecución anterior. Para ello, basta con guardar los identificadores de los vídeos ya vistos y añadir los nuevos resultados a un CSV. A continuación se presenta un script reproducible de Python con TikTok Scraper API: busca vídeos por palabra clave, procesa las dos estructuras de respuesta documentadas y mantiene una base de datos local de ID.
El objetivo: detectar publicaciones nuevas, no revisar todos los resultados
Un equipo de soporte, un investigador de mercado o un analista de contenido puede necesitar una recopilación periódica de vídeos públicos a partir de una búsqueda sobre un producto. Si se exportan todos los resultados cada vez, los vídeos repetidos dificultan la revisión y las publicaciones nuevas se pierden entre las ya procesadas. Un registro de identificadores permite comparar los resultados de cada ejecución: el CSV contiene solo los vídeos nuevos para este proceso y los campos principales devueltos en la respuesta.
Este registro responde a una pregunta concreta, pero práctica: ¿qué elementos aparecieron en la respuesta de la ejecución actual y no estaban en el conjunto de ID guardado? Resulta útil para crear una cola de revisión manual y para pasar los datos a una hoja de cálculo o a un análisis posterior. La recopilación refleja los resultados de la API para la búsqueda indicada; por sí sola, no describe todas las publicaciones de TikTok.
Qué necesitas
- Python 3.8 o posterior.
- Acceso a TikTok Scraper API y una clave de licencia.
- Una búsqueda que puedas repetir sin cambiar su significado, como el nombre de un producto o una frase concreta.
Guarda la clave en la variable de entorno JSONSCRAPER_TIKTOK_LICENSE_KEY, no en el archivo del script. En el ejemplo, la clave se pasa como el parámetro de consulta license_key, según el esquema de la API. No la muestres en el registro de ejecución.
export JSONSCRAPER_TIKTOK_LICENSE_KEY="tu_clave"
python -m pip install requests
En Windows PowerShell, puedes establecer la variable para la sesión actual así: $env:JSONSCRAPER_TIKTOK_LICENSE_KEY="tu_clave". No añadas secretos reales a Git ni a un CSV compartido.
Integración: ejecutar una búsqueda y normalizar el JSON
La documentación describe la ruta GET /searchVideo, que requiere el parámetro keyword, para buscar vídeos. También se pueden especificar count, una región, un orden, un filtro temporal y un cursor para recorrer los resultados. Este ejemplo mínimo utiliza solo la palabra clave, el número de elementos solicitados y la región de Estados Unidos. La referencia de rutas de TikTok API enumera los nombres exactos de los parámetros.
La estructura de la respuesta de búsqueda requiere atención: el arreglo aweme_list puede estar vacío y los elementos de vídeo pueden encontrarse en search_item_list, con los datos anidados en aweme_info. Por eso, el código comprueba ambas rutas, combina después los elementos y elimina los duplicados según aweme_id. Así se evita que un JSON procesado correctamente se convierta por error en un informe vacío.
import csv
import json
import os
from pathlib import Path
from datetime import datetime, timezone
import requests
BASE_URL = "https://tiktok.evelode.com/searchVideo"
KEYWORD = "nombre del producto"
REGION = "US"
COUNT = 30
STATE_FILE = Path("seen_video_ids.json")
OUTPUT_FILE = Path("new_tiktok_videos.csv")
license_key = os.environ.get("JSONSCRAPER_TIKTOK_LICENSE_KEY")
if not license_key:
raise RuntimeError("Define JSONSCRAPER_TIKTOK_LICENSE_KEY")
response = requests.get(
BASE_URL,
params={
"license_key": license_key,
"keyword": KEYWORD,
"count": COUNT,
"region": REGION,
},
timeout=60,
)
response.raise_for_status()
data = response.json()
# La respuesta de ejemplo contiene un status externo y un objeto tiktok anidado.
if "status" in data and data["status"] != "ok":
raise RuntimeError("La API devolvió un estado distinto de ok")
tiktok = data.get("tiktok") or {}
items = list(tiktok.get("aweme_list") or [])
for entry in tiktok.get("search_item_list") or []:
info = entry.get("aweme_info")
if isinstance(info, dict):
items.append(info)
# Elementos únicos de la respuesta actual, conservando el orden.
current = {}
for item in items:
video_id = item.get("aweme_id")
if video_id:
current[str(video_id)] = item
if STATE_FILE.exists():
seen = set(json.loads(STATE_FILE.read_text(encoding="utf-8")))
else:
seen = set()
new_items = [(video_id, item) for video_id, item in current.items()
if video_id not in seen]
run_time = datetime.now(timezone.utc).isoformat()
fields = ["collected_at_utc", "query", "aweme_id", "created_at",
"author", "description", "share_url", "play_count",
"digg_count", "comment_count", "share_count"]
write_header = not OUTPUT_FILE.exists() or OUTPUT_FILE.stat().st_size == 0
with OUTPUT_FILE.open("a", newline="", encoding="utf-8") as f:
writer = csv.DictWriter(f, fieldnames=fields)
if write_header:
writer.writeheader()
for video_id, item in new_items:
author = item.get("author") or {}
stats = item.get("statistics") or {}
writer.writerow({
"collected_at_utc": run_time,
"query": KEYWORD,
"aweme_id": video_id,
"created_at": item.get("create_time"),
"author": author.get("unique_id") or author.get("nickname"),
"description": item.get("desc"),
"share_url": item.get("share_url"),
"play_count": stats.get("play_count"),
"digg_count": stats.get("digg_count"),
"comment_count": stats.get("comment_count"),
"share_count": stats.get("share_count"),
})
seen.update(current.keys())
STATE_FILE.write_text(json.dumps(sorted(seen)), encoding="utf-8")
print(f"En la respuesta: {len(current)} vídeos únicos; nuevos: {len(new_items)}")
El script escribe celdas vacías para los valores que no aparecen en el JSON: puede que algunos campos y métricas no estén presentes en determinados registros. El código no sustituye los datos ausentes por ceros ni interpreta un cero como falta de datos. La hora de recopilación se registra por separado de la hora de publicación que la API devuelve en el campo create_time.
Cómo funciona la detección de cambios
- La solicitud devuelve una página de resultados de búsqueda para la palabra clave indicada.
- El normalizador reúne registros de
aweme_listysearch_item_list[].aweme_info. - El script elimina los duplicados de la respuesta según el ID del vídeo.
- Los identificadores se comparan con el registro JSON local.
- Los ID nuevos se añaden al CSV y, a continuación, se guarda el conjunto completo de los vistos para la próxima ejecución.


Visualizar este proceso resulta útil al compartir el script con colegas: el CSV es un registro incremental, mientras que el JSON contiene el estado de deduplicación. Se pueden guardar por separado del código y respaldar conjuntamente. Para ejecutarlo en equipo o en la nube, sustituye el archivo JSON local por un almacenamiento persistente adecuado y utiliza una actualización atómica del estado para evitar que ejecuciones paralelas se sobrescriban entre sí.
Ejecución periódica y paginación
Programa ejecuciones periódicas con el planificador del sistema operativo, una tarea de CI o un flujo de trabajo de automatización. No cambies la palabra clave sin registrar su versión: distintas búsquedas forman conjuntos de resultados diferentes, y mezclarlas en un único registro complica la interpretación. Por sencillez, el script utiliza una sola búsqueda; puedes procesar una lista de búsquedas con un bucle y guardar el campo query en cada fila.
La API admite cursor para recorrer los resultados de búsqueda. Si añades paginación, pasa el cursor de la respuesta anterior, guárdalo como un valor opaco y detén el recorrido cuando ya no necesites más páginas. El límite count establece el número de elementos solicitados, pero la cantidad real de registros debe determinarse a partir de la respuesta. Aunque se consulten varias páginas, siguen siendo páginas obtenidas de la búsqueda, no una garantía de cobertura completa de la plataforma.
Este script no incluye deliberadamente una clasificación automática del texto ni conclusiones sobre «tendencias». El CSV permite identificar rápidamente los registros nuevos encontrados; después, un analista puede etiquetarlos por tema, intención o tipo de pregunta y revisar los ejemplos manualmente. Si incorporas un modelo de lenguaje, pásale solo los campos de texto necesarios y pídele que devuelva las categorías junto con el ID original, para poder verificar el resultado y vincularlo con el registro.
Comprobaciones y errores habituales
- Error HTTP.
raise_for_status()detiene la ejecución si el código HTTP está fuera del intervalo de éxito. Comprueba la disponibilidad de la API, los parámetros y la cuenta antes de actualizar el archivo de estado. - El estado de la API no es
ok. El script se detiene antes de escribir resultados si la respuesta contiene un campo de nivel superiorstatuscon otro valor. Así se conserva el registro anterior y se evita confundir una respuesta errónea con una búsqueda sin resultados. - La lista
aweme_listestá vacía. Comprueba tambiénsearch_item_list; el código contempla ambas estructuras. - Los vídeos se repiten entre ejecuciones. Es normal que haya páginas de resultados de búsqueda solapadas: no vuelven a aparecer en el informe si sus ID ya están guardados.
- Falta una métrica. La celda queda vacía. En los cálculos, distingue los valores ausentes de los ceros reales.
- Se pierde el estado. El script considerará nuevos todos los ID devueltos. Haz copias de seguridad de
seen_video_ids.jsonjunto con el CSV o utiliza una base de datos persistente.
Al automatizar el proceso, guarda datos de diagnóstico sin incluir la clave: hora de ejecución, código HTTP, estado de la API, número de registros procesados y cantidad de ID nuevos. Esto ayuda a distinguir entre la ausencia de vídeos nuevos y una solicitud fallida. Si necesitas volver a comprobar el esquema, puedes archivar por separado la respuesta completa original; limita el acceso y el periodo de conservación de acuerdo con las necesidades del equipo.
Resultado
Después de ejecutar el script, tendrás un CSV con vídeos cuyos ID son nuevos para el registro, sus descripciones, enlaces y los campos públicos disponibles, además de un estado JSON para comparar con la próxima ejecución. Este resultado es adecuado como cola compacta de entrada para equipos de soporte, análisis o contenido. Puedes consultar la descripción de la API y las opciones de acceso en la página de TikTok Scraper API; comprueba los parámetros exactos de búsqueda en la referencia oficial de rutas.