Cómo no perder resultados de búsqueda de TikTok al analizar JSON

Al buscar videos en TikTok mediante una API, puede que no estén en el array que el procesador espera encontrar primero. En una respuesta de jsonscraper verificada para la solicitud a `/searchVideo`, el campo `aweme_list` estaba vacío y los elementos con datos de video aparecían en `search_item_list[].aweme_info`. Si el código solo lee `aweme_list`, guardará cero videos aunque la respuesta contenga resultados. Para los desarrolladores, esto plantea un problema concreto de fiabilidad: extraer ambas formas de datos y normalizarlas en una sola lista antes de guardarlas en una base de datos o enviarlas a un informe.

La comprobación de un ejemplo real y la descripción del endpoint están disponibles en la especificación de la API de jsonscraper y la documentación del endpoint de TikTok. La instantánea del esquema incluida en la especificación está fechada el 25 de octubre de 2026; muestra la estructura de una respuesta concreta, pero no garantiza que todos los campos estén presentes en solicitudes posteriores.

Por qué el analizador puede devolver una lista vacía

El endpoint `GET https://tiktok.evelode.com/searchVideo` busca videos mediante el parámetro obligatorio `keyword`. La documentación también enumera `cursor`, `count`, `cache_timeout`, `date_posted`, `sort_by` y `region`. En el esquema de la respuesta observada, el objeto de nivel superior contiene `status` y un objeto anidado `tiktok`; dentro de este aparecen `cursor`, `has_more`, `status_code`, `aweme_list` y `search_item_list`.

En una observación concreta, realizada con una palabra clave y `count=3`, el array `aweme_list` estaba vacío. Al mismo tiempo, `search_item_list` contenía elementos cuyos datos de video estaban en `aweme_info`. Estos objetos podían incluir el ID del video, el texto de la publicación, la URL, el autor y estadísticas como el número de reproducciones, «Me gusta» o comentarios. Los campos descritos corresponden al esquema observado; aun así, el procesador debe aceptar que algunos valores no estén presentes.

La conclusión práctica es que una solicitud HTTP satisfactoria y un array no vacío en uno de los campos esperados son dos comprobaciones distintas. Primero, verifica el estado externo y la presencia de `tiktok`; después, recopila los videos de cada ubicación documentada. Para el análisis, guarda los ID y la respuesta original: así podrás rastrear cómo se extrajo y normalizó cada registro.

Normaliza la respuesta antes de guardarla

Una interfaz útil entre la API y tu sistema es una función que reciba el objeto anidado `tiktok` y devuelva elementos unificados. Debe procesar ambos arrays, omitir elementos que no sean diccionarios o estén vacíos y eliminar duplicados de un mismo video por `aweme_id`. Deja los contadores vacíos cuando el proveedor no los devuelva: cero indicaría un valor medido, mientras que `None` señala que el campo no estaba disponible.

A continuación se muestra un ejemplo mínimo para Python 3.8 o posterior. Realiza una solicitud, comprueba el estado de transporte y el estado de nivel superior, normaliza los dos formatos de resultados e imprime los campos seleccionados. La clave se lee desde una variable de entorno y no se muestra en el registro.

import os
import requests

BASE_URL = "https://tiktok.evelode.com"


def extract_videos(tiktok):
    candidates = []
    aweme_list = tiktok.get("aweme_list") or []
    if isinstance(aweme_list, list):
        candidates.extend(aweme_list)

    search_items = tiktok.get("search_item_list") or []
    if isinstance(search_items, list):
        for item in search_items:
            if isinstance(item, dict):
                candidates.append(item.get("aweme_info"))

    unique = {}
    for video in candidates:
        if not isinstance(video, dict):
            continue
        video_id = video.get("aweme_id")
        if video_id:
            unique[video_id] = video
    return list(unique.values())


license_key = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
response = requests.get(
    BASE_URL + "/searchVideo",
    params={
        "license_key": license_key,
        "keyword": "python tutorial",
        "count": 10,
        "region": "US",
    },
    timeout=30,
)
response.raise_for_status()
payload = response.json()

if payload.get("status") != "ok":
    raise RuntimeError("TikTok API returned a non-ok status")

tiktok = payload.get("tiktok")
if not isinstance(tiktok, dict):
    raise RuntimeError("Response has no tiktok object")

for video in extract_videos(tiktok):
    stats = video.get("statistics") or {}
    author = video.get("author") or {}
    print({
        "aweme_id": video.get("aweme_id"),
        "desc": video.get("desc"),
        "share_url": video.get("share_url"),
        "author": author.get("unique_id"),
        "play_count": stats.get("play_count"),
        "digg_count": stats.get("digg_count"),
        "comment_count": stats.get("comment_count"),
    })

Instala la dependencia con el comando python -m pip install requests, configura `JSONSCRAPER_TIKTOK_LICENSE_KEY` en el entorno de ejecución y guarda el archivo, por ejemplo, como `search_videos.py`. Los parámetros de la solicitud coinciden con los nombres documentados: `keyword`, `count` y `region`; `license_key` se pasa como parámetro de consulta. El código supone que la respuesta contiene `status: "ok"`, como en el ejemplo registrado. Si la API devuelve otro estado, el procesamiento se detiene antes de pasar una estructura dudosa a la siguiente etapa.

Cómo convertir el ejemplo en una recopilación repetible

Para una exportación puntual, basta con escribir los elementos normalizados en JSON Lines o en una tabla. En un proceso continuo, guarda además la respuesta original junto con la hora de recepción y la consulta de búsqueda. Una tabla independiente de videos normalizados puede usar `aweme_id` como clave: si un resultado se repite, se actualiza el registro, y si el mismo ID aparece en ambos arrays, no se crea un duplicado.

Para solicitar la página siguiente, la documentación indica el parámetro `cursor`: pasa el valor recibido en la respuesta anterior. Trátalo como un token opaco; guárdalo y devuélvelo sin transformarlo. El bucle de paginación debe terminar cuando `has_more` indique que no hay más resultados o cuando la API no proporcione un cursor válido; limita el número de páginas por ejecución para evitar que una lógica defectuosa genere un bucle infinito. Las fuentes registradas confirman el nombre del parámetro y la presencia de los campos `cursor` y `has_more` en el esquema observado, pero no garantizan que los resultados sean exhaustivos.

Si supervisas varias frases de búsqueda, guarda cada frase junto con el ID del video y la hora de recopilación. Así podrás crear vistas por consulta, comparar los resultados entre ejecuciones y enviar los ID nuevos a una cola para su clasificación posterior. Este sistema describe los resultados de búsqueda recibidos; el conjunto de datos depende de la consulta, la región, la hora y los elementos que la API devuelva efectivamente.

Comprueba la calidad de los datos, no solo que la solicitud haya funcionado

Después de la normalización, conviene registrar algunos indicadores técnicos de tu canal de procesamiento: el número de registros de cada array, el número de ID únicos, la proporción de elementos sin ID y la proporción de elementos sin estadísticas. Estas métricas describen el procesamiento de una respuesta concreta, no la popularidad de los videos. Por ejemplo, un aumento de elementos sin `play_count` indica que el análisis debe conservar el valor como desconocido y señalar que el campo está incompleto, en lugar de asignarle cero.

No supongas que todos los videos tendrán siempre el mismo conjunto de estadísticas. Para conservar los datos sin procesar, guarda el JSON completo; para la tabla analítica, selecciona solo los campos necesarios y permite valores `NULL`. Si cambia el formato de la respuesta, el archivo original permitirá volver a ejecutar el normalizador sin hacer otra solicitud.

Pasa la clave de la API mediante los secretos de CI o las variables de entorno del orquestador. No la incluyas en URL que se guarden en los registros, no imprimas el objeto de parámetros de la solicitud ni almacenes la clave junto con las respuestas originales. Si el proceso se ejecuta de forma programada, añade un límite de tiempo para las solicitudes, gestión de errores HTTP e intentos repetidos con pausas; guarda el cursor siempre junto a la consulta de búsqueda correspondiente para no mezclar páginas de distintas búsquedas.

Resultado: una tabla unificada en lugar de videos omitidos

Tras la normalización, el código de las etapas posteriores recibe una sola lista de videos, tanto si el elemento llegó en `aweme_list` como en `search_item_list[].aweme_info`. El ID permite eliminar repeticiones, y los campos opcionales quedan explícitamente vacíos. Esto reduce el riesgo de generar informes vacíos por leer un solo array y hace más predecible la siguiente etapa: exportación, filtrado o clasificación.

Puedes empezar la comprobación en la página de TikTok Scraper API, donde se indica el endpoint base de la API y se ofrece acceso a una demostración. Para la integración, utiliza la documentación oficial y comprueba primero el procesamiento con un número reducido de elementos; si hace falta, aumenta `count` y continúa con el cursor documentado. El resultado será una capa de datos ordenada para tus tareas, no una suposición de que se ha cubierto todo TikTok.