techhorizonlabs/perfil-de-canal-de-youtube

Perfil de canal de YouTube

scripts/channel_profile.py lee datos públicos del canal a través de la API de datos v3 de YouTube e imprime un informe en Markdown, o JSON con --json. Utiliza únicamente la API oficial. Nunca carga páginas web de YouTube y no escribe nada en disco.

Antes de ejecutarlo

1. La persona necesita un proyecto de Google Cloud con la API de datos v3 de YouTube habilitada y una clave de API restringida a esa API.
2. La clave reside en la variable de entorno YOUTUBE_API_KEY. Nunca la pongas en un prompt, archivo o chat, y nunca la imprimas. Si no está configurada, detente y pide a la persona que la configure. No busques claves en ningún otro lugar.
3. Instala la única dependencia: pip install -r scripts/requirements.txt (requests).

Ejecución

python3 scripts/channel_profile.py @handle
python3 scripts/channel_profile.py https://www.youtube.com/@handle --videos 100
python3 scripts/channel_profile.py UCxxxxxxxxxxxxxxxxxxxxxx --json

Opciones: --videos N (subidas recientes a leer, por defecto 50, máximo 500), --json, --no-search, --cpm-low y --cpm-high (por defecto 0.25 y 4.00).

Cómo encuentra el canal

• Una ID de canal o una URL /channel/UC...: channels.list con id.
• Un @handle o URL /@handle: channels.list con forHandle.
• Una URL /user/: forUsername. Una URL /c/ se prueba como handle.
• Si no coincide nada, recurre a search.list para la mejor coincidencia y lo indica en el informe. Verifica el título y la ID antes de confiar en él. --no-search desactiva la alternativa.
• Se rechazan enlaces de videos, enlaces de listas de reproducción y direcciones que no sean de YouTube. Pide el enlace del canal.

Cuota

Llamada	Costo
channels.list	1 unidad
playlistItems.list	1 unidad por cada 50 subidas
videos.list	1 unidad por cada 50 videos
search.list (solo alternativa)	1 llamada de su propio bucket

La ejecución predeterminada cuesta 3 unidades de las 10,000 unidades diarias por defecto. Desde el 1 de junio de 2026, search.list tiene su propio bucket de 100 llamadas al día. Antes de eso, una búsqueda costaba 100 unidades de la cuota principal, por lo que las guías antiguas dirán 100. Las llamadas fallidas siguen consumiendo cuota. La cuota se reinicia a la medianoche, hora del Pacífico. Cada informe finaliza con la cuota utilizada.

Qué informa

De YouTube, tal como se devuelve:

• Suscriptores, redondeados hacia abajo por YouTube a tres cifras significativas. Si el propietario oculta el recuento, el informe dice "Oculto" y no proporciona estimación.
• Vistas totales del canal y el recuento público de videos.
• Vistas, likes y comentarios de cada video reciente.

Derivado por el script, marcado con *:

• Cadencia: mediana de días entre las últimas N subidas, subidas por mes ((N - 1) intervalos / días abarcados x 30.44), y días desde la última subida.
• Mediana y media de vistas de videos recientes. Se excluyen transmisiones en vivo y próximas.
• Tendencia: mediana de vistas de las últimas 10 subidas contra las 10 anteriores. Los videos más nuevos han tenido menos tiempo para acumular vistas.
• Interacción: por video (likes + comentarios) / vistas, luego la mediana. Se excluyen videos con likes ocultos. Los videos con comentarios desactivados cuentan como 0 comentarios.
• Shorts frente a formato largo, por duración. Esto es una heurística: 180 segundos o menos cuenta como Short, porque la API no tiene un indicador de Shorts.
• Top 5 de videos recientes por vistas.
• Vistas mensuales estimadas: la suma de las vistas actuales de los videos publicados en los últimos 30 días. Esto excluye las vistas del catálogo anterior. Si la muestra no alcanza los 30 días, el informe lo indica y solicita un --videos más grande. Esta comprobación asume que la lista de reproducción de subidas lista primero las más recientes, como suele hacerlo.

La política III.E.4.h de la API de YouTube permite cifras derivadas solo junto a los totales propios de YouTube, con una nota clara de que no provienen de YouTube. El informe hace ambas cosas. Mantén esa nota cada vez que cites una cifra marcada con estrella.

Método de ingresos

bajo  = vistas mensuales estimadas / 1,000 x US$0.25
alto = vistas mensuales estimadas / 1,000 x US$4.00

US$0.25 a US$4.00 es el rango de CPM predeterminado publicado por Social Blade (socialblade.com/youtube/calculator). El informe imprime la fórmula con los números reales. Son solo ingresos por anuncios. Excluye patrocinios, membresías, compras, ingresos por afiliados y financiación de fans. El RPM real varía según el nicho, el país de la audiencia y el formato. Los ingresos de Shorts se agrupan en términos diferentes. Un canal fuera del Programa de Socios de YouTube no genera ingresos por anuncios. Llámalo siempre un rango estimado, nunca ingresos.

Errores

Salida	Significado	Qué hacer
0	Informe impreso
2	Entrada incorrecta, clave faltante o no se encontró el canal	Corrige la entrada, o pide a la persona la clave o el enlace correcto
3	Cuota agotada	Detente. Informa a la persona que se reinicia a la medianoche, hora del Pacífico. No reintentes en un bucle ni cambies de clave
4	Otro error de API, como una clave no válida o la API no habilitada	Muestra el mensaje a la persona
5	Error de red	Reintenta una vez, luego infórmalo

Los errores imprimen la cuota utilizada antes del fallo. Cada mensaje e informe se limpia de la clave antes de imprimirse.

Reglas

• Solo API oficial. No rasques páginas de YouTube para llenar un vacío. Informa el vacío.
• No almacenes en caché nada más allá de la ejecución. No guardes respuestas sin procesar de la API. Si la persona conserva el informe, las estadísticas de la API no pueden almacenarse por más de 30 días (política III.E.4.b).
• Solo datos públicos. Los datos demográficos de la audiencia no son públicos: consulta la habilidad creator-audience.

Verificado el 5 de noviembre de 2026 contra la referencia de la API de datos de YouTube, la página de cuota, el historial de revisiones y las políticas para desarrolladores. Las pruebas del script se ejecutan sin conexión contra fixtures. No se ha ejecutado contra la API en vivo aquí.