Cómo raspar publicaciones de TikTok y métricas de video con Python

TL;DR:

• Un raspador de videos de TikTok comienza con una cuenta pública conocida. Resuelve el nombre de usuario con scraper.tiktok.user.detail, luego pasa su sec_uid a scraper.tiktok.user.work.
• La respuesta de las publicaciones es una muestra limitada. La solicitud documentada acepta cursor y count, pero una respuesta no debe describirse como la historia completa de publicaciones de un creador.
• Las métricas de publicaciones públicas necesitan contexto. Almacena el tiempo de colección junto a los recuentos de reproducciones, me gusta, comentarios, compartidos, coleccionados y republicados, porque esos valores pueden cambiar.
• Las publicaciones de fotos y los campos opcionales requieren un análisis tolerante. Un elemento válido puede tener campos de medios o subtítulos en blanco, y el tipo de publicación debe provenir del registro devuelto en lugar de una suposición.
• Las exportaciones estables mantienen los identificadores como cadenas. Preserva el JSON sin procesar y escribe un CSV normalizado para análisis.
• Libre para comenzar. Las nuevas cuentas de Scrapeless incluyen crédito gratuito; crea una cuenta en el Tablero de Scrapeless.

Introducción: una lista de publicaciones es una muestra con marca de tiempo

El feed público de un creador mezcla identificadores, descripciones, metadatos de medios, hashtags, música y recuentos de participación acumulados. Convertir ese feed en una tabla útil requiere dos llamadas a la API y una pequeña cantidad de normalización cuidadosa.

Esta guía construye un raspador de videos de TikTok para una cuenta conocida. Resuelve el sec_uid de la cuenta, solicita un conjunto limitado de publicaciones públicas y escribe una fila de CSV por elemento. El flujo de trabajo no etiqueta la primera respuesta como un archivo completo, y no trata los recuentos de reproducciones públicas como alcance único.

Para un mapa de los actores de perfil, publicaciones y tienda disponibles, lee la guía de la API de Raspador de TikTok.

Qué Puedes Recoger De Una Cuenta Conocida

El actor scraper.tiktok.user.work devuelve un array items para un sec_uid proporcionado. Un elemento de publicación puede contener su ID y URL, descripción, texto de la etiqueta, tiempo de creación, recuentos de participación pública, detalles de medios, hashtags, idioma, banderas de fijado y anuncio, música, subtítulos, permisos y contexto del perfil.

Esa forma admite varias salidas prácticas:

• Un inventario de publicaciones para una cuenta pública seleccionada
• Una tabla de descripciones, hashtags, fechas y URLs de publicaciones
• Una instantánea de participación en un momento dado
• Una cola de revisión para publicaciones fijadas, promocionales o relacionadas con el comercio electrónico
• Una tabla de entrada limpia para la clasificación de contenido posterior

El actor no documenta el texto de comentarios, demografía de audiencia, listas de seguidores, espectadores únicos, conversiones o atribución de ingresos. Esos campos no deberían aparecer en la salida normalizada como sustitutos inferidos.

Por Qué Usar Una API De Raspador De TikTok

Un actor gestionado devuelve JSON estructurado de una solicitud HTTP estable. El llamador trabaja con campos nombrados en lugar de mantener selectores para una página renderizada, manejar diseños específicos de medios, o traducir cada cambio visual en actualizaciones de analizador.

La solicitud aún necesita un alcance claro. Un raspador de publicaciones de TikTok debería comenzar con una cuenta seleccionada por el usuario, registrar cuándo se recogió la muestra y conservar suficiente contexto de origen para auditar cada fila. El intercambio HTTP sigue la semántica definida por RFC 9110, mientras que la documentación JSON de Python describe la serialización utilizada a continuación.

Requisitos Previos

• Una cuenta de Scrapeless y un token de API del Tablero de Scrapeless
• Python 3 con su biblioteca estándar
• El nombre de usuario público de la cuenta a inspeccionar
• Un propósito permitido, un tamaño de muestra definido y una política de retención
• Un token de API activo para los bloques de código a continuación; expórtalo como SCRAPELESS_API_KEY

Los ejemplos se marcan como una brecha de requisitos previos porque no se incrusta ningún token de API en este artículo. Son rutas de solicitud completas, pero los lectores deben proporcionar su propia credencial y nombre de usuario objetivo.

Cómo Funciona El Raspador De Publicaciones De TikTok

El flujo de trabajo utiliza un endpoint y dos actores:

POST https://api.scrapeless.com/api/v1/scraper/request

1. Envía unique_id a scraper.tiktok.user.detail.
2. Lee sec_uid de la respuesta del perfil.
3. Envía ese valor a scraper.tiktok.user.work con un count limitado.
4. Normaliza el items devuelto sin inventar campos faltantes.

La documentación oficial para desarrolladores de TikTok también separa la lista de videos autorizados por la cuenta en una operación de lista de videos dedicada, lo cual es un recordatorio útil de que la resolución de identidad y la recuperación de contenido son pasos distintos. Consulta la documentación de List Videos de TikTok para esa interfaz de primera parte.

Parámetros de Solicitud

El actor de perfil requiere unique_id, escrito sin el @ inicial. Su respuesta puede incluir account_id, unique_id y sec_uid junto con campos de perfil público y estadísticas.

El actor de publicaciones requiere sec_uid. También acepta cursor como una cadena y count como un número entero positivo. Los valores predeterminados documentados son "0" y 35. La documentación confirma la entrada del cursor, pero la respuesta mostrada no establece un campo de continuación universal ni una garantía de historial completo.

Captura Rápida Con curl

Esta primera solicitud resuelve el identificador de cuenta necesario por el actor de publicaciones.

Nota: El código a continuación requiere un token de API Scrapeless en SCRAPELESS_API_KEY y un nombre de usuario público seleccionado por el lector.

curl --request POST 'https://api.scrapeless.com/api/v1/scraper/request' \
  --header "x-api-token: ${SCRAPELESS_API_KEY}" \
  --header 'content-type: application/json' \
  --data '{
    "actor": "scraper.tiktok.user.detail",
    "input": {"unique_id": "tiktok"}
  }'

Copia el sec_uid devuelto en una solicitud scraper.tiktok.user.work, o deja que el programa en Python realice ambas llamadas.

Sobre la Respuesta

La respuesta de publicaciones contiene un array de items. Trata cada elemento como un registro de publicación pública observada. Los siguientes grupos son útiles al construir una tabla:

Empieza a Raspar con Scrapeless

¡Potencia tu raspado web y flujo de trabajo de automatización con Scrapeless!
Regístrate hoy y obtén $5 de crédito gratuito — sin necesidad de tarjeta de crédito.

Reclama tu crédito gratuito ahora en el Tablero de Scrapeless.

Integrando la API en Python

El programa a continuación resuelve el perfil, recopila hasta 20 elementos del cursor documentado inicial, guarda la respuesta en crudo y exporta una tabla de métricas compacta. La documentación del módulo CSV de Python explica el escritor utilizado para el archivo normalizado.

Nota: El código a continuación requiere un token de API Scrapeless en SCRAPELESS_API_KEY; la parte de la solicitud no podría ejecutarse sin esa credencial externa.

import csv
import json
import os
from datetime import datetime, timezone
from urllib.request import Request, urlopen

ENDPOINT = "https://api.scrapeless.com/api/v1/scraper/request"
TOKEN = os.environ["SCRAPELESS_API_KEY"]
USERNAME = os.environ.get("TIKTOK_USERNAME", "tiktok").lstrip("@")


def run_actor(actor, actor_input):
    payload = json.dumps({"actor": actor, "input": actor_input}).encode()
    request = Request(
        ENDPOINT,
        data=payload,
        headers={
            "x-api-token": TOKEN,
            "content-type": "application/json",
        },
        method="POST",
    )
    with urlopen(request, timeout=60) as response:
        return json.load(response)


profile = run_actor(
    "scraper.tiktok.user.detail",
    {"unique_id": USERNAME},
)

posts = run_actor(
    "scraper.tiktok.user.work",
    {"sec_uid": profile["sec_uid"], "cursor": "0", "count": 20},
)

collected_at = datetime.now(timezone.utc).isoformat()
items = posts.get("items") or []

with open("tiktok-posts-raw.json", "w", encoding="utf-8") as raw_file:
    json.dump(posts, raw_file, ensure_ascii=False, indent=2)

fieldnames = [
    "collected_at",
    "account_unique_id",
    "post_id",
    "post_url",
    "description",
    "created_at",
    "play_count",
    "like_count",
    "comment_count",
    "share_count",
    "collect_count",
    "repost_count",
    "is_pinned",
    "hashtags",
]

with open("tiktok-post-metrics.csv", "w", newline="", encoding="utf-8") as csv_file:
    writer = csv.DictWriter(csv_file, fieldnames=fieldnames)
    writer.writeheader()
    for item in items:
        writer.writerow({
            "collected_at": collected_at,
            "account_unique_id": profile.get("unique_id", USERNAME),
            "post_id": str(item.get("id") or item.get("post_id") or ""),
            "post_url": item.get("url") or item.get("post_url") or "",
            "description": item.get("description") or "",
            "created_at": item.get("create_time") or item.get("date") or "",
            "play_count": item.get("play_count"),
            "like_count": item.get("like_count"),
            "comment_count": item.get("comment_count"),
            "share_count": item.get("share_count"),
            "collect_count": item.get("collect_count"),
            "repost_count": item.get("repost_count"),
            "is_pinned": item.get("is_pinned"),
            "hashtags": "|".join(
                str(tag.get("name", tag)) if isinstance(tag, dict) else str(tag)
                for tag in (item.get("hashtags") or [])
            ),
        })

print(f"Saved {len(items)} sampled post records for @{USERNAME}")

Los nombres de campo de respaldo en el normalizador evitan que una clave opcional falle la exportación. Compáralos con la respuesta del actor actual antes de fijar un esquema de producción, y mantén el JSON en crudo para que la transformación pueda ser revisada más tarde.

Interpretar Publicaciones de Fotos, Banderas Ancladas y Campos Vacíos

Una URL de video vacía no prueba que la recopilación haya fallado. TikTok admite formatos de contenido más allá de un objeto de video convencional, y los campos opcionales de medios, música o subtítulos pueden estar vacíos en una respuesta válida. Basa la etiqueta de formato en la estructura devuelta y conserva un estado de unknown cuando la evidencia está incompleta.

Una bandera anclada describe la colocación en el perfil en el momento de la recopilación. No establece cuándo el creador ancló la publicación, por qué fue anclada, o si permaneció anclada después de la instantánea.

La misma disciplina se aplica a las métricas públicas. Un conteo de reproducción es un contador acumulativo de la plataforma expuesto con la publicación; no es un conteo de personas únicas. Los me gusta, comentarios, comparticiones, colecciones y reposts describen interacciones visibles, no atribuciones de campaña.

Manejar Cursor y Alcance de Muestra con Cuidado

La solicitud documentada acepta cursor, pero el ejemplo de respuesta disponible no confirma una sola regla de paginación que se pueda copiar en cada cliente. Usa la primera respuesta como una muestra limitada a menos que la respuesta en vivo y la documentación actual proporcionen un valor de continuación verificado.

Registra el cursor de la solicitud, el conteo solicitado, el conteo de elementos devueltos y el tiempo de recopilación junto a la salida. Estos cuatro campos hacen visible el alcance. También evitan que un tablero convierta “20 publicaciones observadas” en “todas las publicaciones” a través de un total sin etiqueta.

Problemas Comunes a Prevenir

• Pasar unique_id al actor de publicaciones. Resuelve el perfil primero y usa su sec_uid.
• Convertir IDs largos a números. Mantén los identificadores de cuenta y publicación como cadenas.
• Tratar lo faltante como cero. Un campo métrico o de medios opcional vacío debe permanecer desconocido hasta que su significado se establezca.
• Llamar a la primera respuesta un historial completo. Etiquétalo como una muestra con su cursor, conteo solicitado y tiempo de recopilación.
• Eliminar la URL de origen. La URL de la publicación da a los revisores una ruta directa de regreso al elemento público observado.
• Mezclando recuentos acumulativos con el crecimiento por intervalos. Una única instantánea proporciona niveles; se necesitan instantáneas repetidas con marcas de tiempo para los deltas.

Scrapeless empaqueta al actor bajo Scraping API. Revisa la página de precios actual antes de establecer un horario de colección de producción.

Conclusión: preserva la muestra antes de analizarla

Un scraper de videos de TikTok confiable resuelve una cuenta conocida, solicita una muestra de publicaciones limitadas y preserva la respuesta antes de aplanarla. La salida útil es más que un CSV de métricas: incluye identificadores de cadena estables, URLs de origen, un sello de tiempo de colección, JSON en bruto y una declaración honesta del alcance.

¿Listo para recolectar métricas públicas de publicaciones de TikTok?

Únete al Discord de Scrapeless o a la comunidad de Telegram para comparar notas de implementación. Crea una cuenta en el Tablero de Scrapeless cuando estés listo para probar el flujo de trabajo.

FAQ

P: ¿Qué es un scraper de videos de TikTok?

Un scraper de videos de TikTok recolecta campos de publicaciones públicas soportadas y los devuelve en una forma estructurada. El flujo de trabajo en esta guía utiliza un actor de perfil para resolver sec_uid y un actor de publicaciones para devolver una muestra de items.

P: ¿Puede un scraper de publicaciones de TikTok obtener cada publicación de una cuenta?

La respuesta de un actor no debe describirse como cada publicación. Los documentos de la solicitud cursor y count, pero la cobertura completa depende de una regla de continuación verificada, el contenido público accesible de la cuenta y una colección exitosa a través del alcance previsto.

P: ¿Qué métricas de video de TikTok están disponibles?

Los elementos de la publicación pueden incluir recuentos públicos de reproducciones, Me gusta, comentarios, compartidos, recolectados y republicados. Estos son contadores en un momento dado y no representan alcance único, ventas o atribución de campañas.

P: ¿Cómo deben manejarse las publicaciones de fotos?

Las publicaciones de fotos deben ser analizadas a partir de los campos presentes en el ítem devuelto. Mantén los campos de medios como anulables y evita declarar un scrape fallido simplemente porque un campo de video convencional esté vacío.

P: ¿El flujo de trabajo necesita proxies o un parser de navegador?

El actor administrado maneja su superficie de recopilación detrás de la solicitud de API. El llamador proporciona identificadores válidos, limita la muestra, valida la respuesta y almacena el resultado de manera responsable.

P: ¿Es legal hacer scraping de publicaciones públicas de TikTok?

La legalidad depende de la jurisdicción, el propósito, los datos, el método de acceso y los términos aplicables. Recoge solo los campos públicos necesarios para un uso permitido, minimiza la retención y busca asesoría legal para el proyecto específico.