API TikTok Scraper: cómo obtener datos de videos en JSON con jsonscraper

Si una aplicación necesita información sobre un video concreto de TikTok, lo más práctico es empezar con una sola solicitud y comprobar qué datos devuelve. Después, se puede validar la respuesta y prepararla para almacenarla o analizarla.

La página de TikTok Scraper API de jsonscraper enumera rutas para videos, usuarios, búsquedas, hashtags, música y otros tipos de datos. A continuación, veremos la solicitud documentada getVideoByID y cómo procesar su respuesta de forma segura. Los ejemplos se basan en los materiales del proveedor; antes de utilizarlos, compruébalos con una clave activa y la documentación actualizada.

Primera solicitud: obtener información de un video

La documentación de getVideoByID en Postman especifica el método GET y el parámetro video_id. El ejemplo también muestra region y cache_timeout. La dirección base publicada en la página del servicio es https://tiktok.evelode.com.

Ejemplo de solicitud con cURL:

export JSONSCRAPER_LICENSE_KEY="tu_clave"

curl --get "https://tiktok.evelode.com/getVideoByID" \
  --data-urlencode "video_id=7106855913906081070" \
  --data-urlencode "license_key=$JSONSCRAPER_LICENSE_KEY" \
  --data-urlencode "region=US"

El ID del ejemplo procede de la solicitud publicada. Sustitúyelo por el ID del video que quieras comprobar. Guarda la clave en una variable de entorno o en un gestor de secretos: no la incluyas en un repositorio público, en JavaScript del lado del cliente ni en los registros.

Postman describe region como un código de región e indica US como valor predeterminado. Para cache_timeout, la documentación señala una ventana de caché predeterminada de 3600 segundos; el valor 0 desactiva la caché. Si este parámetro es necesario para tu caso, puedes enviarlo explícitamente:

curl --get "https://tiktok.evelode.com/getVideoByID" \
  --data-urlencode "video_id=7106855913906081070" \
  --data-urlencode "license_key=$JSONSCRAPER_LICENSE_KEY" \
  --data-urlencode "region=US" \
  --data-urlencode "cache_timeout=0"

Esta es una adaptación de los parámetros publicados para la ruta, no una garantía de que todas las respuestas tengan la misma estructura ni de que desactivar la caché sea adecuado para cualquier tarea. Antes de implementarlo, comprueba la autenticación y los parámetros en la colección actual: Postman puede enviar la clave mediante una API Key configurada, mientras que el ejemplo de cURL anterior la muestra como parámetro de URL.

La misma solicitud en Python

A continuación se muestra una versión con la biblioteca estándar de Python. Forma una solicitud GET, envía los parámetros y gestiona errores de red, errores HTTP y JSON no válido.

import json
import os
from urllib.error import HTTPError, URLError
from urllib.parse import urlencode
from urllib.request import Request, urlopen

base_url = "https://tiktok.evelode.com/getVideoByID"
license_key = os.environ.get("JSONSCRAPER_LICENSE_KEY")

if not license_key:
    raise RuntimeError("Define la variable JSONSCRAPER_LICENSE_KEY")

params = {
    "video_id": "7106855913906081070",
    "license_key": license_key,
    "region": "US",
}

url = f"{base_url}?{urlencode(params)}"
request = Request(url, method="GET")

try:
    with urlopen(request, timeout=30) as response:
        status_code = response.status
        payload = json.loads(response.read().decode("utf-8"))
except HTTPError as error:
    print(f"Error HTTP: {error.code}")
    raise
except URLError as error:
    print(f"Error de red: {error.reason}")
    raise
except json.JSONDecodeError:
    raise RuntimeError("No se pudo analizar la respuesta del servicio como JSON")

print("Estado HTTP:", status_code)
print("Claves de nivel superior:", list(payload.keys()))

Esta adaptación se basa en la solicitud documentada, pero no es un ejemplo que el proveedor haya probado por separado para Python. Tampoco describe todas las respuestas posibles del servicio. Como la clave se envía en la URL, no registres la URL completa: podría contener un secreto.

Cómo validar la respuesta JSON

La respuesta de Postman publicada contiene el campo status y un objeto anidado tiktok.aweme_detail con datos del video y su autor. Es un ejemplo de la estructura de una respuesta, no una garantía de que el esquema permanezca invariable. Puedes consultarlo en el ejemplo de respuesta de getVideoByID.

Al leer campos anidados, comprueba cada nivel:

def get_video_details(payload):
    tiktok = payload.get("tiktok")
    if not isinstance(tiktok, dict):
        return None

    details = tiktok.get("aweme_detail")
    if not isinstance(details, dict):
        return None

    return details

details = get_video_details(payload)

if details is None:
    print("La respuesta no contiene el objeto de datos de video esperado")
else:
    video_id = details.get("id")
    description = details.get("desc")
    author = details.get("author")

    print("ID:", video_id)
    print("Descripción:", description)
    print("Autor:", author)

Los nombres de los campos proceden del ejemplo publicado. Usar .get() no significa que los campos sean obligatorios: permite procesar una respuesta en la que no estén los valores esperados. Si la lógica de la aplicación depende de un campo concreto, comprueba que esté presente en las respuestas de tu caso y prevé qué hacer si falta.

Conviene separar tres comprobaciones:

1. Transporte: si se recibió una respuesta HTTP y cuál es su estado.
2. Formato: si se pudo analizar el cuerpo de la respuesta como JSON.
3. Contenido: si están presentes los datos que necesita la aplicación.

Que el análisis de JSON se complete correctamente no significa que la respuesta contenga el objeto necesario. Para diagnosticar problemas, registra los errores técnicos y los resultados de las comprobaciones, ocultando las claves.

De una solicitud a un flujo de trabajo

Para un prototipo basta con enviar una solicitud y mostrar algunos valores. Para procesar datos con regularidad, divide el trabajo en etapas:

Solicitud → validación → normalización → deduplicación → almacenamiento.

• Solicitud. Obtén la respuesta mediante la ruta documentada y guarda por separado el estado técnico.
• Validación. Comprueba que el cuerpo se pueda analizar como JSON y que contenga los datos necesarios para la tarea concreta.
• Normalización. Traslada los valores necesarios a tu propio modelo de datos. No guardes toda la estructura anidada en la base de datos si la aplicación solo necesita algunos campos.
• Deduplicación. Elige un identificador después de comprobar que está presente y que sirve para tu caso. No des por hecho que siempre estará disponible en todas las respuestas.
• Almacenamiento. Si es necesario, guarda por separado la hora de la solicitud y la respuesta original, aparte del registro normalizado. Así podrás entender qué cambios introdujo la aplicación.

Estas son recomendaciones sobre el diseño de la aplicación, no funciones que deban atribuirse al servicio. Separar la respuesta externa del modelo interno también facilita gestionar cambios: los problemas se pueden localizar en la etapa de validación o normalización, en lugar de buscarlos por todo el código.

Para las solicitudes recurrentes, define con antelación cuándo actualizar los datos y qué errores conviene reintentar. Limita el número de reintentos: un bucle infinito no solucionará un parámetro incorrecto ni un problema de autenticación.

Caché y región

En la descripción de la ruta getVideoByID, el parámetro cache_timeout define el tiempo de caché en segundos: se indica un valor predeterminado de 3600 segundos, y 0 desactiva la caché. El parámetro region se describe como un código de país; la documentación incluye US como ejemplo. Antes de implementarlo, contrasta esta información con la documentación actual de la solicitud en Postman.

La mera existencia de una opción de caché no confirma que una respuesta concreta esté actualizada. Si la vigencia de los datos es importante, comprueba los resultados de solicitudes repetidas con datos de tu caso y elige el comportamiento adecuado.

Qué tareas puedes explorar después

La página del producto enumera rutas para buscar videos y usuarios, hashtags, ubicaciones, música y tendencias. Entre los ejemplos están searchVideo, searchHashtag, getUserFeed y getTrendingFeed. Este es el mapa de rutas publicado por el proveedor, no una comprobación independiente de cada una. Consulta los parámetros y la forma de la respuesta en la documentación de cada ruta: no se pueden trasladar automáticamente desde el ejemplo de getVideoByID.

jsonscraper recomienda usar la colección de Postman para configurar la clave y ejecutar solicitudes. Puede ser una forma práctica de probar una ruta concreta antes de escribir una integración. El servicio también enumera casos de uso de automatización, pero debes comprobar por separado la compatibilidad de cada flujo en tu configuración. Si exportas la colección o la compartes, asegúrate de que no incluya una clave activa.

Qué comprobar antes de usarlo en una aplicación

Antes de incorporar la solicitud a un proceso periódico, pruébala con los videos y parámetros que necesita el proyecto:

• Si la solicitud se ejecuta con una clave activa y un ID válido.
• Cómo gestiona la aplicación un parámetro incorrecto o ausente.
• Qué ocurre si el JSON es válido, pero falta el campo necesario.
• Cómo se gestionan los errores HTTP, los fallos de red y los tiempos de espera.
• Qué campos sirven para identificar y deduplicar datos en tu caso concreto.
• Cómo cambia el resultado de una solicitud repetida con distintos valores de cache_timeout, si utilizas este parámetro.

Registra la fecha de la comprobación, los parámetros sin secretos y un ejemplo anonimizado de la respuesta. Una solicitud satisfactoria solo confirma el funcionamiento de un caso concreto en unas condiciones concretas; no demuestra la estabilidad de todas las rutas y respuestas.

Empieza con un caso reproducible

Prueba getVideoByID con el video que necesitas, examina el JSON real y escribe un controlador que tenga en cuenta los campos ausentes y los errores. Después, si hace falta, amplía el proceso con normalización, deduplicación y almacenamiento.

La documentación de jsonscraper ofrece un punto de partida: la dirección base y el mapa de rutas. Aun así, el código de producción debe validar la respuesta concreta, proteger la clave y contemplar los casos en que los datos difieran de la estructura esperada.