Michael JohnsonSi un equipo necesita comprobar cómo divulgan los creadores su relación con una marca en videos públicos de TikTok, el primer resultado útil no es un veredicto automático, sino una lista compacta de videos con su descripción, enlace y las palabras clave encontradas. A continuación, presentamos un flujo de trabajo: enviar una consulta de búsqueda mediante TikTok Scraper API de jsonscraper, unificar los dos formatos de respuesta y guardar un CSV para que lo revise un especialista.
El objetivo: encontrar videos que convenga revisar
La búsqueda manual por nombre de empresa es difícil de repetir de forma uniforme: hay que recopilar los resultados uno por uno y los motivos para seleccionarlos quedan en el navegador. Una búsqueda automatizada permite guardar la consulta, la fecha de ejecución y los materiales encontrados en una tabla para que el equipo pueda revisar los videos con una lista común.
En este caso, «candidato para revisión» significa únicamente un video de los resultados de búsqueda devueltos cuya descripción contiene una palabra o frase definida de antemano. Por ejemplo, puede ser «publicidad», «colaboración» o «patrocinado». Este filtro de texto ayuda a dirigir la atención de una persona, pero no evalúa el video ni determina si cumple los requisitos aplicables.
Esta distinción es importante para un equipo de marketing. Las recomendaciones de la Comisión Federal de Comercio de Estados Unidos describen la divulgación de una relación material con una marca como una obligación que depende del contexto del mensaje; para los videos, la FTC recomienda tener en cuenta que la divulgación sea visible y audible. Una búsqueda en las descripciones puede detectar algunas señales de texto, pero para decidir hay que ver la publicación y evaluar su contexto. La guía de la FTC para creadores explica estas condiciones con ejemplos.
El resultado: un CSV con el motivo de selección
El flujo de trabajo escribirá una fila por cada identificador de video único e incluirá el texto de la descripción, el enlace, el nombre del autor, las métricas públicas disponibles y los marcadores coincidentes. También añadiremos la consulta de búsqueda original y la hora de recopilación. Así, la tabla podrá enviarse a una cola de trabajo y, más adelante, será posible entender por qué se incluyó un video concreto.
El diccionario de marcadores lo define un editor o especialista en cumplimiento. Empieza con el idioma y los términos que realmente se usan en tu campaña; después, revisa los resultados y amplía la lista si hace falta. Los valores del código siguiente son deliberadamente sencillos: debes adaptarlos a la marca, el mercado y el idioma del contenido.
Conexión a TikTok Scraper API
La documentación de jsonscraper indica que la ruta para buscar videos es GET /searchVideo, en la dirección base https://tiktok.evelode.com. El parámetro obligatorio es keyword; entre los parámetros adicionales se encuentran count, date_posted, sort_by y region. La clave se pasa mediante license_key, así que guárdala en una variable de entorno, no en el código ni en el CSV. Los nombres exactos de los parámetros y la ruta aparecen en la referencia de endpoints de TikTok; puedes consultar información sobre el producto y el acceso en la página de TikTok Scraper API.
Hay una característica importante de la respuesta que afecta a la exhaustividad del analizador local: los datos pueden estar en tiktok.aweme_list o en tiktok.search_item_list[].aweme_info. Por eso, el script comprueba ambas matrices. Si la búsqueda devuelve una lista vacía, generará un CSV vacío en lugar de inventar filas para suplir la falta de resultados.
Ejemplo en Python: búsqueda, filtro y CSV
El ejemplo solo utiliza la biblioteca estándar de Python 3.8 o posterior. Antes de ejecutarlo, define JSONSCRAPER_TIKTOK_LICENSE_KEY en el entorno. La solicitud utiliza keyword y pasa la clave en el parámetro de consulta license_key, tal como indica la especificación.
import csv
import json
import os
import sys
from datetime import datetime, timezone
from urllib.parse import urlencode
from urllib.request import Request, urlopen
API_KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
KEYWORD = "Acme"
MARKERS = ["publicidad", "colaboración", "colaboración", "patrocinador", "ad", "sponsored"]
params = {
"license_key": API_KEY,
"keyword": KEYWORD,
"count": 30,
"sort_by": "date-posted",
"date_posted": "this-month",
"region": "US",
}
url = "https://tiktok.evelode.com/searchVideo?" + urlencode(params)
request = Request(url, headers={"Accept": "application/json"})
with urlopen(request, timeout=30) as response:
payload = json.load(response)
if payload.get("status") != "ok":
raise RuntimeError("API returned a non-ok outer status")
tiktok = payload.get("tiktok") or {}
items = list(tiktok.get("aweme_list") or [])
for entry in tiktok.get("search_item_list") or []:
info = entry.get("aweme_info") or {}
if info:
items.append(info)
seen = set()
rows = []
collected_at = datetime.now(timezone.utc).isoformat()
for item in items:
video_id = item.get("aweme_id")
if not video_id or video_id in seen:
continue
seen.add(video_id)
description = item.get("desc") or ""
lowered = description.casefold()
matched = [word for word in MARKERS if word.casefold() in lowered]
if not matched:
continue
author = item.get("author") or {}
stats = item.get("statistics") or {}
rows.append({
"collected_at_utc": collected_at,
"search_keyword": KEYWORD,
"video_id": video_id,
"share_url": item.get("share_url") or "",
"description": description,
"matched_markers": "; ".join(matched),
"author_name": author.get("nickname") or "",
"author_id": author.get("unique_id") or "",
"play_count": stats.get("play_count", ""),
"digg_count": stats.get("digg_count", ""),
"comment_count": stats.get("comment_count", ""),
"share_count": stats.get("share_count", ""),
})
fields = [
"collected_at_utc", "search_keyword", "video_id", "share_url",
"description", "matched_markers", "author_name", "author_id",
"play_count", "digg_count", "comment_count", "share_count",
]
with open("tiktok_review_queue.csv", "w", newline="", encoding="utf-8-sig") as output:
writer = csv.DictWriter(output, fieldnames=fields)
writer.writeheader()
writer.writerows(rows)
print(f"Saved {len(rows)} review candidates to tiktok_review_queue.csv")Primero, el script comprueba el estado externo; después, lee el objeto tiktok y combina las variantes de matriz disponibles. La deduplicación por aweme_id evita filas repetidas si un video aparece en las dos rutas de respuesta. Las métricas se guardan tal como se reciben; si falta un valor, queda en blanco en lugar de convertirse en cero.
El ejemplo utiliza parámetros documentados para /searchVideo: date_posted admite el valor this-month, sort_by admite date-posted y region acepta un código de país. El valor de count determina el tamaño de los resultados solicitados, pero no garantiza una lista completa de publicaciones. Para paginar, conserva el cursor devuelto como un valor opaco y pásalo en el parámetro cursor.
Revisión humana y automatización de las ejecuciones
Entrega el CSV a la persona responsable de la revisión junto con instrucciones breves: abrir el enlace, ver el video y el contexto de la descripción, registrar la conclusión y añadir un comentario si el marcador tiene otro sentido. Por ejemplo, el filtro automático no distingue entre una divulgación publicitaria y un debate sobre cómo funciona la publicidad. La revisión humana resuelve esta brecha semántica.
Para recopilar datos de forma repetible, ejecuta el script según un calendario mediante cron, un planificador de CI o un orquestador de tareas. Guarda el CSV con la fecha de ejecución o carga las filas en una tabla con una clave única compuesta por el identificador del video y la fecha de observación. Si necesitas un registro de auditoría, guarda también la respuesta JSON original con controles de acceso: así podrás volver a comprobar la transformación y explicar de dónde salió cada fila.
En una versión de producción conviene añadir el tratamiento de errores de red y HTTP, limitar los reintentos y enviar notificaciones en caso de fallo. No imprimas la URL completa de la solicitud: contiene la clave de acceso. Si el equipo tiene varios usuarios, es recomendable guardar el secreto en un gestor de secretos del entorno de ejecución y restringir el acceso a los archivos resultantes de acuerdo con las normas internas.
Qué aporta esta lista
Tras ejecutar el script, el equipo tendrá una selección reproducible de videos encontrados mediante una frase clave y un motivo explícito para incluir cada candidato en la cola. Desde la tabla se podrán excluir manualmente las coincidencias irrelevantes, asignar a una persona revisora y agrupar los resultados por marcador o autor. Si la recopilación se ejecuta con regularidad, también habrá un historial de los videos que aparecieron en los resultados devueltos en cada fecha.
Este método sirve para la detección inicial y la asignación de materiales, no para emitir automáticamente una conclusión sobre el cumplimiento de las normas. Está limitado por los resultados de búsqueda, la palabra clave elegida, la configuración de la consulta y los marcadores de texto. Para revisar una colaboración concreta, compara el video con el brief y la información disponible para tu equipo; después, evalúa el mensaje en sí conforme a las normas aplicables.
Para empezar, comprueba el acceso y los parámetros actuales en la página del producto TikTok Scraper API y consulta la documentación oficial de la API para verificar el formato de respuesta y las opciones de integración.
