Michael JohnsonEl equipo de marketing observa que aparecen videos sobre un producto nuevo en TikTok, pero comprobar varios hashtags a diario de forma manual resulta difícil. Para comparar publicaciones y métricas visibles a lo largo del tiempo, hace falta una recopilación repetible con marca de tiempo, archivo de las respuestas originales y verificación de los cambios.
Para este prototipo, TikTok Scraper API de jsonscraper es una opción adecuada: la página del producto enumera rutas para hashtags, usuarios, videos y búsquedas. El primer paso es probar la ruta necesaria y el formato de respuesta en Postman y, después, trasladar a Python la configuración verificada. Así se puede crear un proceso repetible que extraiga solo los campos que realmente aparecen en la respuesta.
El objetivo: observar la evolución, no un único video popular
Una publicación con muchas visualizaciones puede llamar la atención, pero para planificar una campaña resulta más útil entender cuántos videos nuevos se detectan sobre un tema y cómo cambian las métricas públicas de las publicaciones ya encontradas. Por ejemplo, a una tienda en línea de artículos deportivos le interesa evaluar el flujo de videos sobre una modalidad concreta de entrenamiento antes de preparar creatividades relacionadas.
La revisión manual dificulta las comparaciones: el conjunto de resultados cambia, las métricas se acumulan y los empleados pueden anotarlas en formatos distintos. Si se guarda una instantánea de cada ejecución con la hora de recopilación y el JSON original, el equipo obtiene un historial de sus propias observaciones y puede volver a procesar los datos si cambia el esquema analítico.
La automatización consta de varios pasos: verificar la ruta y los parámetros, solicitar datos según un calendario, guardar la respuesta, confirmar su estructura y, después, extraer los campos necesarios. La tabla resultante se puede utilizar para crear gráficos, clasificar temas o elaborar un informe.
Qué confirma la documentación de la API
La página de TikTok Scraper API indica la dirección base https://tiktok.evelode.com y enumera las rutas de la clase Hashtag: GET /getHashtagInfo, GET /getHashtagFeed y GET /getHashtagFeedByID. La página también muestra un ejemplo de solicitud a otra ruta con el parámetro license_key y describe cómo configurar la clave en una colección de Postman.
Para GET /getHashtagFeed, la especificación oficial de rutas indica el parámetro obligatorio query (la URL del hashtag o el nombre de la etiqueta), además de los parámetros opcionales cursor, count, region y cache_timeout. Se espera que la respuesta del feed incluya un arreglo tiktok.aweme_list; entre los campos enumerados para cada elemento figuran aweme_id, desc, create_time, share_url, los datos del autor y statistics. Algunos campos pueden faltar, así que comprueba el JSON real antes de procesarlo.
La colección de jsonscraper en Postman permite hacer una solicitud de prueba, comprobar la respuesta real y obtener un ejemplo de prueba para validar el código más adelante. Para la autenticación se envía license_key; guarda la clave en una variable de entorno y no la incluyas en los registros.
Primero, comprueba la solicitud en Postman
Empieza con un solo hashtag de prueba. En la colección, selecciona la ruta del feed de hashtags, configura license_key de la manera indicada en la documentación y pasa el nombre de la etiqueta en query. Si hace falta, añade count y el código de país en region. Ejecuta la solicitud y comprueba el estado HTTP, el campo de nivel superior status y el contenido de tiktok.aweme_list.
Guarda la respuesta correcta como un archivo JSON de prueba. Úsalo para comprobar que estén presentes el identificador de la publicación, la descripción, la hora de publicación, el enlace y las estadísticas. Incluye un campo en el esquema analítico solo después de confirmar que llega con el tipo esperado.
Guarda la clave API en una variable de entorno, no en el archivo de código fuente. Si la clave se transmite en la URL, ocúltala al registrar la solicitud para que la dirección completa no termine en los registros.
Cliente de Python para solicitar y archivar datos
La ruta y los nombres de los parámetros siguientes corresponden a la especificación publicada: para un hashtag se usa query y la autenticación se transmite mediante license_key. El ejemplo es compatible con Python 3.8 o posterior y guarda la respuesta original junto con los metadatos de la ejecución.
import json
import os
from datetime import datetime, timezone
from pathlib import Path
import requests
BASE_URL = "https://tiktok.evelode.com"
API_KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
def fetch_hashtag_feed(hashtag: str) -> dict:
params = {
"license_key": API_KEY,
"query": hashtag,
"count": 20,
}
response = requests.get(
f"{BASE_URL}/getHashtagFeed",
params=params,
timeout=45,
)
response.raise_for_status()
payload = response.json()
if payload.get("status") != "ok":
raise RuntimeError("La API devolvió un estado distinto de ok")
return payload
def archive_response(hashtag: str, payload: dict) -> Path:
collected_at = datetime.now(timezone.utc).isoformat()
safe_tag = hashtag.lstrip("#").replace("/", "_")
output_dir = Path("data/raw") / safe_tag
output_dir.mkdir(parents=True, exist_ok=True)
filename = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ.json")
file_path = output_dir / filename
file_path.write_text(
json.dumps(
{
"hashtag": hashtag,
"collected_at": collected_at,
"response": payload,
},
ensure_ascii=False,
indent=2,
),
encoding="utf-8",
)
return file_path
if __name__ == "__main__":
tag = "#temadeejemplo"
payload = fetch_hashtag_feed(tag)
saved_path = archive_response(tag, payload)
print(f"Archivo guardado: {saved_path}")
Antes de ejecutar el programa, configura la variable de entorno JSONSCRAPER_TIKTOK_LICENSE_KEY. La solicitud utiliza el parámetro query confirmado y limita el número de elementos solicitados mediante count. Se comprueban el estado HTTP y el estado del JSON; el archivo guarda los datos reales para procesarlos más adelante. Prueba la ejecución con un solo hashtag antes de añadir un calendario y análisis.
Cómo normalizar los datos sin hacer suposiciones frágiles
La documentación indica que la respuesta del feed contiene el arreglo tiktok.aweme_list. Antes de transformarlo, comprueba que tiktok sea un objeto y que aweme_list sea una lista. Para cada elemento, extrae solo los campos confirmados, por ejemplo, aweme_id, desc, create_time, share_url y los valores de statistics, si están presentes.
La tabla interna puede incluir el hashtag de la consulta, la hora de recopilación, el identificador del video y las métricas seleccionadas. Para una métrica opcional o ausente, guarda un valor vacío: una métrica no disponible no equivale a un cero medido. Conserva las respuestas originales por separado para reconstruir la tabla sin hacer otra solicitud.
Si cambia el formato de la respuesta, la validación de tipos debe detener el procesamiento incorrecto y generar un mensaje de diagnóstico. Guarda el JSON de prueba junto con la prueba del analizador: servirá para comprobar que la nueva versión del código siga procesando el esquema conocido.
Métricas basadas en observaciones repetidas
Si la respuesta ofrece contadores, guarda cada observación con una marca de tiempo. Para una misma publicación, compara los valores de dos ejecuciones y calcula el cambio observado durante ese intervalo. Para vincularlos, utiliza aweme_id, indicado en la especificación, y comprueba que esté presente en cada elemento.
El número de publicaciones detectadas por primera vez en un día se puede calcular a partir de los resultados de tus ejecuciones. Esta métrica describe el flujo devuelto por consultas concretas con determinados parámetros y una frecuencia específica. Permite comparar tus propias instantáneas si el método de recopilación se mantiene constante.
Un informe básico puede mostrar el número de publicaciones nuevas detectadas por día, la distribución de los contadores disponibles y la variación de los valores de los videos encontrados más de una vez. Añade la hora de la solicitud y el nombre del archivo original para que los analistas puedan comprobar el origen de cada registro.
Calendario y gestión de errores
Cuando la solicitud y el análisis estén verificados, ejecuta el script según un calendario, por ejemplo, mediante cron, GitHub Actions u un orquestador de datos. Guarda la lista de hashtags en una configuración aparte para poder añadir y quitar temas sin modificar la lógica del cliente.
Para las ejecuciones automáticas, configura un tiempo de espera, un número limitado de reintentos ante errores de red temporales y el registro del estado HTTP y la duración de la solicitud. No registres la clave. Si falla el análisis, conserva información de diagnóstico segura y avisa a la persona responsable.
La especificación admite la paginación mediante el parámetro cursor para el feed de hashtags. Si la necesitas, guarda el cursor de la respuesta y envíalo en la solicitud siguiente sin transformarlo; procesa solo los resultados devueltos y controla has_more, si está presente. Si las solicitudes de varios hashtags devuelven la misma publicación, elige la clave de deduplicación según el objetivo: contar la publicación por separado para cada hashtag o contabilizar solo los videos únicos.
Clasificación y automatización de informes
Una vez que tengas filas verificadas, puedes añadir la clasificación de las descripciones de video por temas definidos: el campo desc aparece en el esquema del elemento. Un modelo puede agrupar las publicaciones por formato, por ejemplo, tutoriales, reseñas o experiencias de usuarios. Conserva el texto original, la etiqueta, la versión de la instrucción y el resultado; envía los casos dudosos a revisión humana.
Calcula las métricas numéricas con código convencional para que las ejecuciones repetidas produzcan resultados aritméticos reproducibles. Un clasificador resulta útil para procesar texto; el informe final debe vincular sus conclusiones con filas y fechas de observación concretas.
En un flujo sin código, se pueden conectar las mismas etapas con una herramienta de automatización: calendario, solicitud HTTP con la configuración verificada, validación de la respuesta, almacenamiento del JSON, transformación de los campos confirmados y aviso de errores. Primero verifica el contrato en Postman y después trasládalo a Python, n8n o Make.
Resultado esperado y siguiente paso
Una vez configurado el sistema, el equipo tendrá un archivo de respuestas de la API y una tabla de observaciones para los hashtags seleccionados. Esto ayudará a encontrar publicaciones nuevas, comparar las métricas disponibles a lo largo del tiempo y elegir materiales para un análisis más detallado. Para obtener resultados comparables, mantén constantes el calendario, los parámetros de las solicitudes y las reglas de normalización.
Empieza con una sola ruta y una respuesta real: ejecuta /getHashtagFeed con el parámetro query, guarda el JSON y luego añade el análisis de campos y el calendario. La página de TikTok Scraper API muestra la dirección base y el mapa de rutas, mientras que la especificación de rutas contiene los nombres de los parámetros necesarios para implementar el cliente.