Michael JohnsonDespués de lanzar una campaña, al equipo puede resultarle útil comprobar qué videos públicos aparecen en los resultados de búsqueda para determinadas palabras. Las búsquedas manuales son difíciles de repetir y comparar varios días después. Un pequeño recolector puede ejecutar las mismas consultas según un calendario y archivar las respuestas con la fecha y la frase de búsqueda, para que un analista pueda revisar los registros y preparar su propio resumen.
Esta guía presenta una canalización de archivo en Python para guardar resultados de búsquedas de frases fijas. A diferencia del seguimiento de hashtags o cuentas individuales, aquí la clave para comparar consiste en repetir las mismas frases de búsqueda y guardar una instantánea independiente de cada respuesta. La página de la API TikTok Scraper de jsonscraper indica la dirección base y la ruta GET /searchVideo; en la documentación de esta ruta, la frase de búsqueda se pasa mediante el parámetro obligatorio keyword.
Objetivo y límites de la medición
Imaginemos que un especialista en marketing quiere recopilar cada día los resultados de varias frases fijas: el nombre de un producto, una categoría y una descripción del problema del cliente. Para cada consulta, el sistema guarda la hora de recopilación y la respuesta de la API. Después de revisar un ejemplo de respuesta, se pueden normalizar los campos que realmente estén presentes en el JSON, como el identificador del video o los contadores públicos, si los hay.
El archivo responde a una pregunta concreta: ¿qué registros devolvió la búsqueda de la frase guardada durante esta ejecución? Si la respuesta contiene métricas, las observaciones repetidas pueden mostrar la diferencia entre los valores registrados en distintos momentos. Esa diferencia corresponde a las instantáneas observadas y al intervalo entre ellas; para hacer la comparación, conserva ambas horas de recopilación y el mismo campo.
Guarda la consulta junto con la respuesta. La composición de los resultados corresponde a una frase de búsqueda concreta y a un momento determinado. Por eso, el archivo sirve para seguir los resultados de las consultas seleccionadas, no como una visión completa de todo el contenido de TikTok. Los identificadores, las respuestas originales y las marcas de tiempo ayudan a comprobar el origen de cada fila de la tabla posterior.
Comprueba la ruta y sus parámetros
El mapa de rutas de la API de TikTok indica la dirección base https://tiktok.evelode.com y GET /searchVideo. La especificación actual de la API señala que keyword es un parámetro de búsqueda obligatorio; entre los parámetros opcionales figuran cursor, count, cache_timeout, date_posted, sort_by y region. Para la autorización se envía license_key. También puedes consultar la información de la ruta en la documentación del SDK de Python.
Los parámetros count y date_posted ayudan a definir el tamaño de la respuesta y el filtro temporal; sort_by acepta los valores documentados most-liked, relevance o date-posted. Si utilizas paginación, pasa el cursor recibido en la respuesta anterior como un valor opaco, sin calcularlo por tu cuenta. Para que el archivo diario sea comparable, guarda los parámetros de la consulta y la versión de tu propio código junto con los datos.
El ejemplo siguiente usa un valor pequeño de count para una prueba y fija la región en US. Antes de iniciar la recopilación diaria, comprueba una consulta, su estado HTTP y la estructura del JSON. El esquema de respuesta puede contener los videos encontrados en tiktok.aweme_list o en tiktok.search_item_list, donde el objeto del video se encuentra en aweme_info; el código admite ambas formas observadas.
Prepara el proyecto
Crea un entorno virtual e instala requests:
python -m venv .venv
source .venv/bin/activate
pip install requestsEn PowerShell, el entorno se activa con el comando .venv\Scripts\Activate.ps1. Define la clave y la lista de frases de búsqueda mediante variables de entorno. Para la API de TikTok, usa el nombre documentado de la variable JSONSCRAPER_TIKTOK_LICENSE_KEY:
export JSONSCRAPER_TIKTOK_LICENSE_KEY="tu_clave"
export TIKTOK_QUERIES="nombre del producto,categoría del producto,problema del cliente"Recopila y guarda las instantáneas
El ejemplo envía una consulta por cada frase a la ruta documentada y después guarda el JSON original, la hora de recopilación y los parámetros utilizados. El nombre del archivo incluye la fecha y la frase de búsqueda. La clave se guarda en el entorno y no se incluye en el archivo.
import json
import os
import re
import time
from datetime import datetime, timezone
from pathlib import Path
import requests
BASE_URL = "https://tiktok.evelode.com"
ENDPOINT = "/searchVideo"
LICENSE_KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
QUERIES = [
item.strip()
for item in os.environ["TIKTOK_QUERIES"].split(",")
if item.strip()
]
OUT = Path("data")
OUT.mkdir(exist_ok=True)
def safe_name(text):
cleaned = re.sub(r"[^a-zA-Z0-9_-]+", "_", text).strip("_")
return cleaned[:80] or "query"
def fetch(query):
params = {
"license_key": LICENSE_KEY,
"keyword": query,
"count": 10,
"region": "US",
}
response = requests.get(
BASE_URL + ENDPOINT,
params=params,
timeout=60,
)
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 extract_videos(payload):
tiktok = payload.get("tiktok") or {}
videos = list(tiktok.get("aweme_list") or [])
for item in tiktok.get("search_item_list") or []:
video = item.get("aweme_info") or {}
if video:
videos.append(video)
return videos
for query in QUERIES:
collected_at = datetime.now(timezone.utc).isoformat()
payload = fetch(query)
record = {
"collected_at": collected_at,
"query": query,
"request": {
"endpoint": ENDPOINT,
"keyword": query,
"count": 10,
"region": "US",
},
"videos_found": len(extract_videos(payload)),
"payload": payload,
}
filename = OUT / f"{collected_at[:10]}_{safe_name(query)}.json"
filename.write_text(
json.dumps(record, ensure_ascii=False, indent=2),
encoding="utf-8",
)
print(f"Respuesta guardada para la consulta: {query}")
time.sleep(1)
print(f"Respuestas guardadas: {len(QUERIES)}")Este recolector mínimo realiza una consulta por frase con count=10. Para una recopilación más amplia, añade paginación mediante cursor: continúa las consultas pasando el valor del cursor de la respuesta hasta que la API indique que hay más resultados, y guarda cada respuesta por separado. El cursor y el número de resultados determinan una ejecución concreta; el JSON guardado permite comprobar más adelante qué devolvió cada consulta.
El ejemplo comprueba el status externo y después lee el objeto tiktok. Recopila elementos de aweme_list y también de search_item_list[].aweme_info, si se encuentra esta forma. Los campos posibles de un video incluyen el identificador, la descripción, el autor, el enlace y las estadísticas; algunos campos pueden faltar. Por eso, guarda la respuesta completa y comprueba la presencia de cada campo al normalizarla.
El intervalo de un segundo es una pausa entre las solicitudes del propio script, no una afirmación sobre los límites del servicio. Configura la frecuencia y los reintentos de acuerdo con las condiciones de acceso y la documentación. El parámetro cache_timeout está documentado para las búsquedas; permite definir el tiempo de almacenamiento en caché en segundos, y según la especificación el valor 0 desactiva la caché. Añádelo a la consulta cuando ese comportamiento se ajuste a tu caso.
Añade normalización basada en la respuesta real
Después de la primera ejecución, abre el archivo guardado y examina la estructura de payload. La función extract_videos del ejemplo recopila elementos de los dos lugares documentados en los que pueden aparecer las formas de búsqueda en la respuesta. Identifica las claves exactas de los campos que necesitas para el análisis. Si un campo no aparece en un registro concreto, guárdalo como valor ausente en lugar de asignarle una cifra supuesta.
Para el procesamiento posterior, resulta útil generar una fila por cada objeto encontrado y añadirle collected_at y query. Puedes guardar los campos confirmados en un CSV o una base de datos y conservar el JSON original en el archivo. Este par permite crear tablas prácticas y, a la vez, comprobar el origen de cada registro.
Si la API devuelve un identificador de video, úsalo para vincular las observaciones del mismo video entre distintas ejecuciones. Conserva cada observación por separado, sin sobrescribir las anteriores. Si no hay un identificador estable, comprueba primero qué atributos permiten relacionar los registros y no des por sentado que las descripciones de texto coincidentes garantizan que sean el mismo video.
Compara las instantáneas y prepara un informe
Después de normalizar los datos, agrupa los registros por un identificador comprobado y ordénalos por hora de recopilación. Para los campos de contadores, puedes calcular la diferencia entre dos valores consecutivos con código convencional. Por ejemplo, pasar de 12 400 a 18 900 significa que el valor del contador cambió en 6 500 entre esas instantáneas. Indica en el informe las fechas de observación y el campo original para que el lector pueda comprobar el cálculo.
Una estructura útil para la tabla final incluye la frase de búsqueda, el identificador de la publicación, la hora de recopilación y los campos seleccionados de la respuesta. El resumen puede agruparse por consulta y ordenarse según un contador confirmado. Así, el equipo tendrá una lista verificable de los registros devueltos para revisarlos; implementa la tabla o el mensaje en un paso independiente, después de examinar el esquema real.
Al principio, guarda los archivos JSON localmente. Cuando la recopilación sea periódica, traslada las filas normalizadas a PostgreSQL o a un almacén de datos analíticos, y las respuestas originales a un almacenamiento de objetos con la fecha y la consulta en el nombre. Guardar el original resulta especialmente útil cuando ajustas el analizador: puedes volver a ejecutarlo sobre datos históricos sin consultar de nuevo la API.
Programa la recopilación
Para crear un archivo diario, ejecuta el script con cron u otro planificador disponible en tu entorno. Por ejemplo, una tarea puede ejecutar el archivo de Python una vez al día y pasarle la clave y las frases de búsqueda mediante variables de entorno. Antes de usarlo de forma periódica, comprueba una consulta, luego la lista completa y solo después configura el calendario.
Para que la ejecución sea fiable, guarda el estado de cada consulta, limita el número de reintentos ante errores temporales y marca la recopilación como incompleta si una frase falla. No incluyas la clave en los mensajes de error. También conviene separar los archivos por fecha y nombre de consulta para que una ejecución repetida no sobrescriba la instantánea anterior.
Elige la frecuencia según la tarea y el volumen de consultas. Para una revisión diaria basta con una ejecución al día; una recopilación más frecuente tiene sentido cuando al equipo le importan los cambios durante el día. Empieza con una lista corta de frases, comprueba la utilidad de los resultados devueltos y amplía la recopilación dentro de las condiciones de acceso y las normas de uso de datos.
Usa IA para agrupar temas
Una vez confirmado el esquema de la respuesta, puedes enviar los campos de texto seleccionados a un modelo para agrupar descripciones según temas definidos de antemano o preparar un breve borrador de resumen. Junto a la clasificación, conserva el identificador original de la publicación, la frase de búsqueda y el fragmento de texto en que se basa la categoría. Así, el analista podrá pasar de la conclusión del modelo al registro original.
Calcula las diferencias numéricas, la ordenación y la eliminación de duplicados con código convencional. Un modelo sirve para procesar texto y redactar el informe; los contadores y las marcas de tiempo deben proceder de las respuestas guardadas. Separar estas operaciones permite comprender el origen de cada conclusión.
Revisa manualmente parte de las categorías automáticas y guarda las correcciones como ejemplos de prueba. Si tipos distintos de publicaciones acaban con frecuencia en el mismo grupo, aclara las definiciones de las categorías y vuelve a comprobarlas. Este proceso ayuda a evaluar la calidad de la clasificación con los datos de tu tarea.
Conclusión: un archivo reproducible y un resumen verificable
Tras ejecutar la consulta documentada con el parámetro keyword, el equipo dispone de un archivo que muestra qué frases se consultaron, cuándo y qué datos devolvió la API para cada una. A partir de ahí, se puede crear una tabla de resultados, comparar los campos confirmados entre instantáneas y preparar una lista de publicaciones encontradas para su análisis manual.
Empieza con una consulta de prueba y luego configura la lista de frases y el calendario. La descripción de la API TikTok Scraper incluye la dirección base y el mapa de rutas; los parámetros de /searchVideo y el formato de la respuesta se describen en la especificación de la API. Archivar respuestas comprobadas crea una base para realizar análisis reproducibles con frases de búsqueda fijas.