Michael JohnsonUn HTTP 200 no garantiza que la supervisión diaria de TikTok haya recopilado vídeos. Los resultados de búsqueda pueden encontrarse en aweme_list o en search_item_list[].aweme_info; un script que solo lea el primer array puede terminar sin errores y guardar un informe vacío. Una comprobación fiable confirma por separado el estado del transporte y el de la aplicación, extrae las dos estructuras admitidas y registra cuántos vídeos únicos se obtuvieron en esa ejecución.
Qué conviene diagnosticar
Imagina esta tarea: cada mañana, un equipo recopila vídeos públicos para varias búsquedas con el fin de detectar nuevas publicaciones sobre un producto. El resultado importante de este proceso es una lista reproducible de registros encontrados, con descripción, autor, fecha de publicación y métricas disponibles. Si el informe aparece vacío de repente, la causa puede estar en el procesamiento de JSON, en un conjunto de resultados que ha cambiado, en la repetición de vídeos ya conocidos o en un fallo real de la solicitud. Una sola cifra —por ejemplo, la longitud de aweme_list— no permite distinguir estos casos.
La ruta de búsqueda /searchVideo de TikTok Scraper API de jsonscraper acepta el parámetro obligatorio keyword y los parámetros adicionales count, cursor, date_posted, sort_by y region. La documentación de la ruta describe la paginación mediante cursor, que debe enviarse como un valor opaco de la respuesta anterior. El parámetro count indica el número deseado de resultados, pero no garantiza una cobertura completa de las publicaciones.
Divide la comprobación en cuatro señales
Un diagnóstico útil consta de cuatro comprobaciones independientes. La primera: la solicitud HTTP se completó correctamente. La segunda: el status externo de la respuesta es ok y el tiktok.status_code interno corresponde a una respuesta satisfactoria. La tercera: el objeto tiktok está presente y se extraen registros de las dos ubicaciones documentadas en la respuesta. La cuarta: tras eliminar duplicados, quedan registros con identificadores aptos para su almacenamiento. Guarda en el registro la cantidad de elementos extraídos antes y después de deduplicarlos: la diferencia permite saber si se produjeron duplicados durante la normalización.
Si falta un campo, déjalo vacío en lugar de sustituirlo por un valor inventado. Por ejemplo, el contador de visualizaciones puede no estar presente en un registro concreto. Guardar el JSON original junto a la fila normalizada permite comprobar más adelante si la información se perdió al analizar los datos o si ya faltaba en la respuesta original.
Solicitud mínima y normalización en Python
La especificación de jsonscraper establece la dirección base https://tiktok.evelode.com y el envío de la clave mediante el parámetro de consulta license_key. El ejemplo siguiente utiliza los parámetros documentados; la clave se lee de una variable de entorno y no se muestra en el registro. Instala la dependencia con el comando python -m pip install requests y, después, define JSONSCRAPER_TIKTOK_LICENSE_KEY en el entorno.
import json
import os
from datetime import datetime, timezone
from pathlib import Path
import requests
BASE_URL = "https://tiktok.evelode.com/searchVideo"
KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
def extract_videos(payload):
"""Recopilar vídeos de las dos estructuras conocidas de la respuesta de búsqueda."""
tiktok = payload.get("tiktok") or {}
videos = []
for item in tiktok.get("aweme_list") or []:
if isinstance(item, dict):
videos.append(item)
for item in tiktok.get("search_item_list") or []:
if isinstance(item, dict):
aweme = item.get("aweme_info")
if isinstance(aweme, dict):
videos.append(aweme)
return videos
def main():
params = {
"license_key": KEY,
"keyword": "ejemplo de búsqueda sobre un producto",
"count": 20,
"region": "US",
}
response = requests.get(BASE_URL, params=params, timeout=30)
response.raise_for_status()
payload = response.json()
if payload.get("status") != "ok":
raise RuntimeError("La API devolvió un estado externo distinto de ok")
tiktok = payload.get("tiktok")
if not isinstance(tiktok, dict):
raise RuntimeError("Falta el objeto tiktok en la respuesta")
if tiktok.get("status_code") != 0:
raise RuntimeError("El status_code interno no es el valor de éxito 0")
raw_videos = extract_videos(payload)
unique = {}
for video in raw_videos:
video_id = video.get("aweme_id")
if video_id:
unique.setdefault(str(video_id), video)
snapshot = {
"collected_at": datetime.now(timezone.utc).isoformat(),
"keyword": params["keyword"],
"status": payload.get("status"),
"status_code": tiktok.get("status_code"),
"raw_items": len(raw_videos),
"unique_items": len(unique),
"has_more": tiktok.get("has_more"),
"cursor": tiktok.get("cursor"),
"videos": list(unique.values()),
}
Path("snapshots").mkdir(exist_ok=True)
stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
Path(f"snapshots/{stamp}.json").write_text(
json.dumps(snapshot, ensure_ascii=False, indent=2),
encoding="utf-8",
)
print({
"status": snapshot["status"],
"status_code": snapshot["status_code"],
"raw_items": snapshot["raw_items"],
"unique_items": snapshot["unique_items"],
"has_more": snapshot["has_more"],
})
if __name__ == "__main__":
main()El script comprueba el nivel de transporte con raise_for_status() y, a continuación, verifica el estado externo, la presencia del objeto tiktok y el status_code interno. Después extrae registros de las dos estructuras de búsqueda, los deduplica mediante aweme_id y guarda una captura con la hora de recopilación. Si no hay registros válidos, el archivo conserva igualmente los datos de la ejecución, lo que permite distinguir entre un resultado vacío guardado y la ausencia de un informe.
Cómo convertir las capturas en una señal para el equipo
Ejecuta el script con un horario establecido mediante cron, CI o un planificador de flujos de trabajo. Guarda las capturas por separado para cada búsqueda o añade la palabra clave al nombre del archivo. Para una tabla de estado basta con registrar la hora de ejecución, el estado, la cantidad de registros extraídos y únicos, y el indicador has_more. Conviene enviar una notificación si la solicitud genera una excepción, faltan partes obligatorias de la respuesta o la cantidad de registros extraídos cambia bruscamente con respecto al historial propio.
Esta comparación detecta una anomalía en el proceso, pero por sí sola no explica su causa. Una cantidad menor de resultados puede reflejar la composición de los resultados actuales, no una avería de la API o del analizador. Por eso conviene guardar el JSON original, comparar parámetros idénticos y comprobar los identificadores encontrados. Elige el umbral de notificación basándote en las observaciones de tu propia búsqueda, no en una cifra universal.
Para paginar, utiliza el cursor de la respuesta y detén el recorrido cuando la API indique que no hay más resultados. Guarda los cursores utilizados y los parámetros de la solicitud para poder reproducir la ejecución. Los parámetros date_posted y sort_by permiten establecer un filtro temporal y un orden; si la tarea requiere comparaciones reproducibles, mantenlos constantes entre ejecuciones.
Cómo interpretar el resultado
Una vez implementado, el equipo obtiene respuestas verificables a tres preguntas prácticas: si se completó la solicitud, dónde están los resultados en el JSON y cuántos vídeos únicos se incluyeron en la captura guardada. Así se reduce el tiempo que transcurre entre una tabla vacía y el diagnóstico: primero se comprueban los estados y la estructura, y después los parámetros, los duplicados y el contenido de la respuesta original.
El esquema de la respuesta y los campos disponibles pueden variar entre registros. En una comprobación en vivo de jsonscraper del 25 de octubre de 2026, la búsqueda devolvió campos de identificador, descripción, autor y estadísticas; los valores de cada registro deben considerarse opcionales. Un informe útil conserva los datos efectivamente recibidos y no sustituye los campos ausentes por ceros.
Puedes empezar por la página de TikTok Scraper API y consultar las rutas y los parámetros exactos en la documentación oficial de la API. Esta comprobación resulta útil antes de iniciar la supervisión: el informe se convierte en un resultado observable cuya calidad se puede diagnosticar.
