Cómo obtener resultados de búsqueda de YouTube: guía práctica
TL;DR
Utiliza la API oficial de datos de YouTube para recopilar campos de resultados de búsqueda pública admitidos, en lugar de construir un scraper contra la interfaz del navegador de YouTube.
Crea un proyecto en Google Cloud, habilita YouTube Data API v3 y obtén una clave API para el ejemplo de búsqueda pública. Las operaciones autorizadas por la cuenta pueden requerir OAuth en su lugar.
Llama a search.list con part=snippet, una consulta, filtros explícitos y type=video cuando el esquema downstream espera videos.
Sigue nextPageToken dentro de un presupuesto de solicitud fijo. Una página puede contener menos elementos de los solicitados, y los resultados de la API no son una copia de una página de búsqueda personalizada en el navegador.
Enriquecer los IDs de video a través de videos.list cuando necesites detalles o estadísticas de video admitidos que los fragmentos de búsqueda no contienen.
Nstdata Crawl puede proporcionar contexto web externo aprobado para un flujo de trabajo de IA; no es un sustituto para el acceso a la API de YouTube, cuotas o reglas de la plataforma.
¿Cómo Puedes Recopilar Resultados de Búsqueda de YouTube de Manera Fiable?
Puedes recopilar resultados de búsqueda pública admitidos de YouTube a través de la API de datos oficial, registrando la consulta, filtros, IDs de video devueltos y tiempo de observación.
Los desarrolladores que buscan "cómo raspar resultados de búsqueda de YouTube" a menudo quieren un conjunto de datos de investigación, un feed de descubrimiento o videos candidatos para una aplicación de IA. La API admitida proporciona a ese flujo de trabajo un contrato documentado de solicitud y respuesta. No reproduce cada estante, anuncio, clasificación personalizada o componente visual de una página de búsqueda de YouTube con sesión iniciada.
Esta distinción es importante para el análisis. La posición de un video en una respuesta de API es una posición de API bajo parámetros registrados, no una clasificación universal de YouTube. Preserva los parámetros con el resultado para que otro ingeniero pueda entender lo que se observó.
Descubre Nstproxy Crawl - Empieza Tu Prueba Gratuita Hoy
Si la aplicación también necesita contenido web de apoyo, Nstdata Crawl puede recuperar páginas externas aprobadas como una fuente de datos separada. Mantén ese límite de colección explícito en lugar de tratar todo el contenido web como intercambiable.
¿Qué Necesitas Antes de Comenzar?
Necesitas una cuenta de Google, un proyecto de Cloud con YouTube Data API v3 habilitado, una clave API adecuada y un entorno de Python que contenga Requests.
Sigue la guía de inicio de YouTube Data API oficial para crear el proyecto, habilitar la API y obtener credenciales. La búsqueda pública puede utilizar una clave API; las operaciones que involucran datos de usuarios autorizados tienen diferentes requisitos de autenticación. Restringe y gestiona las credenciales de acuerdo con tu entorno de implementación, y mantenlas fuera del control de versiones y de los registros.
Configura YOUTUBE_API_KEY en tu entorno local. Opcionalmente, configura YOUTUBE_QUERY; el ejemplo por defecto es python data pipelines. El script utiliza una región fija, preferencia de idioma, ordenamiento y configuración de búsqueda segura para que el resultado tenga un contexto definido.
También necesitas un presupuesto de solicitud. Verifica la disponibilidad actual de cuotas y la cuota de Consultas de Búsqueda en tu propio proyecto de Cloud. No estimes los límites actuales a partir de la cifra de cuota por solicitud de un artículo antiguo. Una prueba pequeña exitosa no establece la capacidad para un rastreo recurrente sin restricciones.
[Captura de pantalla: Proyecto de Google Cloud con YouTube Data API v3 habilitado y su vista de cuota; oculta los detalles sensibles del proyecto y credenciales.]
¿Qué Retorna la API de Búsqueda y Qué Deja Fuera?
La API de búsqueda devuelve recursos de búsqueda y fragmentos, mientras que los campos de video adicionales requieren una solicitud documentada separada.
La referencia de search.list define el endpoint, filtros, paginación y parámetros admitidos. Con type=video, cada resultado aceptado debe proporcionar un ID de video y información del fragmento, como título y contexto del canal. Sin ese filtro, los tipos de resultados pueden diferir del contrato solo de video en este tutorial.
Los fragmentos de búsqueda no proporcionan un objeto de video completo. Si necesitas estadísticas admitidas u otros detalles, recopila los IDs devueltos y utiliza los valores de part apropiados con el método videos.list. Mantén el tiempo de observación de búsqueda separado del tiempo de enriquecimiento porque esas solicitudes pueden suceder en diferentes momentos.
Las configuraciones de región e idioma influyen en la solicitud, pero no hacen que sus resultados sean idénticos a la experiencia del navegador de una persona. Una preferencia de idioma no es un clasificador de idioma estricto para cada video devuelto. Asimismo, un título es un campo de origen, no evidencia verificada para cada afirmación que el video pueda hacer.
¿Cómo Recuperas un Conjunto de Datos de Búsqueda Acotado con Python?
Puedes llamar al endpoint documentado, seguir como máximo dos páginas, desduplicar los IDs de video y guardar los resultados con un manifiesto de ejecución.
Método 1: Utiliza Python para una colección repetible
Mejor para: una aplicación programada que necesita una salida estructurada y un comportamiento de fallo explícito.
Paso 1: Preparar el entorno. Instala Requests en un entorno virtual y establece tu clave de API y consulta. El script no incluye una credencial, no solicita datos privados ni requiere una sesión de navegador iniciada.
Paso 2: Guardar el recolector. Guarda lo siguiente como youtube_search.py. Solicita hasta 25 elementos por página y se detiene después de un máximo de dos páginas. Ese es un presupuesto de aplicación, no una promesa de 50 resultados.
Pre-requisito de credenciales: este ejemplo requiere tu propio proyecto de Google habilitado y YOUTUBE_API_KEY. El código fue verificado con sintaxis y ejercitado con elementos de paginación sintética; no se realizó una solicitud auténtica en vivo a YouTube durante la preparación.
import html
import json
import os
from datetime import datetime, timezone
from pathlib import Path
import requests
api_key = os.environ.get("YOUTUBE_API_KEY")ifnot api_key:raise SystemExit("Set YOUTUBE_API_KEY before running this example")query = os.environ.get("YOUTUBE_QUERY","python data pipelines")filters ={"part":"snippet","type":"video","maxResults":25,"regionCode":"US","relevanceLanguage":"en","order":"relevance","safeSearch":"moderate",}records, seen_ids, seen_tokens =[],set(),set()page_token =Noneposition =0stop_reason ="page_limit"with requests.Session()as session:for page_number inrange(1,3): params ={**filters,"q": query,"key": api_key}if page_token: params["pageToken"]= page_token
try: response = session.get("https://www.googleapis.com/youtube/v3/search", params=params, timeout=(10,30),) payload = response.json()except(requests.RequestException, ValueError):raise SystemExit("Search request failed; inspect transport safely")fromNoneif response.status_code !=200or"error"in payload: reasons = payload.get("error",{}).get("errors",[]) reason = reasons[0].get("reason","unknown")if reasons else"unknown"raise SystemExit(f"YouTube API error: HTTP {response.status_code}, reason={reason}") items = payload.get("items")ifnotisinstance(items,list):raise SystemExit("Unexpected search response: items is not a list") observed_at = datetime.now(timezone.utc).isoformat()for item in items: position +=1 video_id = item.get("id",{}).get("videoId") snippet = item.get("snippet",{})ifnot video_id ornot snippet.get("title"):raise SystemExit("Unexpected video search item")if video_id in seen_ids:continue seen_ids.add(video_id) records.append({"video_id": video_id,"url":"https://www.youtube.com/watch?v="+ video_id,"title": html.unescape(snippet["title"]),"channel_id": snippet.get("channelId"),"channel_title": snippet.get("channelTitle"),"published_at": snippet.get("publishedAt"),"observed_at": observed_at,"api_position": position,"page_number": page_number,}) next_token = payload.get("nextPageToken")ifnot next_token: stop_reason ="end_of_results"breakif next_token in seen_tokens:raise SystemExit("Repeated pagination token; refusing a loop") seen_tokens.add(next_token) page_token = next_token
result ={"query": query,"filters": filters,"raw_items_seen": position,"accepted_unique_videos":len(records),"stop_reason": stop_reason,"items": records,}Path("youtube-search.json.tmp").write_text( json.dumps(result, ensure_ascii=False, indent=2), encoding="utf-8")os.replace("youtube-search.json.tmp","youtube-search.json")print(f"Saved {len(records)} unique videos; stop_reason={stop_reason}")
Paso 3: Ejecutar el recolector. Ejecuta python youtube_search.py. Si las credenciales, el cupo o el transporte fallan, el script se detiene antes de reemplazar la salida aceptada. Su manejo de errores evita imprimir una URL de solicitud completa, lo que podría exponer una clave de API en los parámetros de consulta.
Paso 4: Inspeccionar el manifiesto. Abre youtube-search.json y revisa la consulta, filtros, raw_items_seen, conteo único aceptado y stop_reason. Un resultado de page_limit es una muestra limitada. Un resultado de end_of_results significa que esta secuencia de respuesta no proporcionó otro token; no prueba una cobertura exhaustiva de cada video relevante de YouTube.
Límite: este ejemplo omite deliberadamente reintentos automáticos, enriquecimiento de video, programación y política de almacenamiento a largo plazo. Agrega esos solo con un presupuesto definido y los requisitos actuales de la API.
Método 2: Verificar una respuesta con curl
Mejor para: diagnosticar una solicitud antes de integrarla en una aplicación.
Paso 1: Establecer la clave de API. Utilice el mismo proyecto habilitado y YOUTUBE_API_KEY que el método de Python. Evite pegar la clave en terminales compartidos o capturas de pantalla.
Paso 2: Enviar una pequeña solicitud de búsqueda. Este comando documentado también necesita su propia clave y no fue ejecutado contra una cuenta activa durante la preparación.
Paso 3: Inspeccionar IDs y paginación. Confirme que items contiene IDs de video y fragmentos. Use el nextPageToken devuelto solo cuando otra solicitud se ajuste al presupuesto. No construya un número de página adivinado ni trate un total estimado como un inventario completo.
Límite: curl verifica el transporte y la estructura de respuesta; no proporciona un pipeline de ingestión duradero. Pase a un programa cuando necesite deduplicación, manifiestos, validación y recuperación.
¿Por qué debería evitar raspar la interfaz del navegador de YouTube?
La API oficial proporciona una superficie de integración soportada, y las políticas de desarrollador de la API de YouTube restringen explícitamente el raspado por parte de los clientes de la API.
Las Políticas de Desarrollador de Servicios de API de YouTube contienen una restricción de raspado que cubre el raspado directo o indirecto de aplicaciones de YouTube o Google y la obtención de datos o contenidos raspados de YouTube. Revise los términos aplicables para su caso de uso en lugar de tratar a un actor externo o un punto final interno accesible como un permiso.
La extracción del navegador también crea un contrato técnico diferente. Resultados personalizados, estado de consentimiento, localización, carga diferida y cambios en los diseños hacen que “los resultados de búsqueda” sean ambiguos. Usar la API no elimina cada obligación de política o calidad de datos, pero hace que los campos solicitados y la paginación sean explícitos.
Si su requerimiento es específicamente auditar una experiencia de búsqueda visual, defina ese requerimiento por separado y obtenga un método aprobado. No describa un conjunto de datos de la API como evidencia de clasificación visual.
¿Cómo puede Nstdata Crawl agregar contexto externo a este flujo de trabajo?
Nstdata Crawl puede recuperar páginas web externas aprobadas asociadas con su tema de investigación, mientras el descubrimiento de YouTube permanece dentro del flujo de trabajo de la API oficial.
Es una API de rastreo web para datos listos para LLM. Una aplicación de investigación en IA puede combinar registros de descubrimiento de videos con documentación de origen separado o páginas de referencia pública. Crawl prepara contenido legible y preserva un contexto útil de la página para el indexado posterior. El descubrimiento puede expandir una sección de documentación controlada sin expandirse en enlaces arbitrarios. La aplicación debe mantener los límites de origen y evitar presentar una página web como una transcripción o como evidencia de contenido de video que no ha recuperado.
Descubrimiento del sitio y alcance recursivo: use límites de página, límites de profundidad y patrones de URL para sitios de referencia aprobados. No aplique ese alcance a las páginas de YouTube como una solución alternativa de cuota.
Renderización de JavaScript: recupere contenido de referencia generado en el navegador cuando la fuente permita el flujo de trabajo. Pruebe la página específica antes de programarla.
Formatos para IA e inspección: Markdown soporta indexación de texto, HTML soporta extracción personalizada y los enlaces soportan descubrimiento. Los formatos adicionales documentados incluyen PDF y capturas de pantalla. Una respuesta JSON es una representación de transporte, no un conjunto de reclamos verificados.
Proxies integrados: las llamadas estándar de Crawl utilizan enrutamiento administrado sin configuraciones separadas de Host, Puerto, Nombre de Usuario, Contraseña o Protocolo. El tráfico por proxy puede seguir contribuyendo separadamente al costo.
Paso 1: Configurar una página de referencia aprobada
Abra Dashboard → Crawl Playground y pruebe una URL de referencia, como la documentación pública de Python. Obtenga una clave de API y copie la solicitud generada actual para el formato requerido.
[Captura de pantalla: Crawl Playground con una URL de documentación externa y salida en Markdown; ocultar la clave de API.]
Paso 2: Recuperar el contexto a través de la API
Este ejemplo documentado requiere NSTDATA_API_KEY y no fue ejecutado con una cuenta de cliente. Recupera una página de documentación externa, no datos de YouTube.
curl --fail-with-body --request POST \'https://api.nstdata.io/api/v1/crawl/scrape/submit-sync'\--header"x-api-key: ${NSTDATA_API_KEY:?Set NSTDATA_API_KEY}"\--header'Content-Type: application/json'\--data'{"url":"https://www.python.org/doc/","formats":["markdown"],"onlyMainContent":true,"timeout":60000}'
Paso 3: Validar y mantener las fuentes distinguibles
Verifique la respuesta externa y la finalización anidada, el éxito, el estado de la página y el contenido. Resuelva las referencias de contenido documentadas cuando estén presentes. Almacene la URL de la página externa y el tiempo de observación por separado de los IDs de video y los parámetros de búsqueda. La guía de website-to-JSON explica por qué la recuperación exitosa aún necesita verificaciones de esquema y significado.
Construido sobre datos web listos para LLM
Recupere páginas aprobadas con rastreo específico, renderizado de JavaScript y formatos de contenido para su flujo de trabajo de IA.
¿Por qué falla una colección de búsqueda de YouTube o devuelve menos resultados?
Los fallos suelen involucrar credenciales, cuota, parámetros de solicitud o suposiciones sobre la paginación y la cobertura.
Síntoma
Causa a investigar
Respuesta
Error de clave o permiso
Proyecto incorrecto, API deshabilitada o restricciones de clave incompatibles
Verifica la API habilitada y la configuración de credenciales
Error relacionado con la cuota
El presupuesto relevante del proyecto se ha agotado
Detén el trabajo y verifica las cuotas actuales; no intentes de nuevo en un bucle apretado
Menos elementos de los solicitados
Comportamiento de respuesta normal o resultados coincidentes disponibles
Sigue un token siguiente válido dentro del presupuesto
Los rankings de navegador y API difieren
Diferente representación y contexto de solicitud
Etiqueta la posición de la API con precisión y conserva los filtros
IDs de video duplicados en páginas
Superposición de resultados o cambios durante la recopilación
Deduplica mientras preservas el conteo bruto y la posición observada primero
Vuelve a intentar los fallos de transporte temporales solo con una política limitada y una comprensión del costo de solicitud. Reintentar fallos de autorización o cuota generalmente requiere un cambio en la configuración o en el presupuesto primero. La guía de errores de scraping discute la clasificación de fallos, mientras que el rastreo por lotes cubre la orquestación de trabajos limitados para otras fuentes web.
¿Cómo Deberías Almacenar Datos de Búsqueda para un Producto de IA?
Almacena observaciones de búsqueda con procedencia, reglas de actualización y una clara distinción entre metadatos de descubrimiento y evidencia de contenido.
Mantén un historial de consultas y filtros, IDs aceptados, marcas de tiempo, razones de detención y estado de enriquecimiento. Revisa los requisitos actuales de YouTube antes de elegir comportamiento de retención, actualización, visualización y eliminación. No asumas que el almacenamiento indefinido es apropiado solo porque un campo provino de una solicitud de búsqueda pública.
Para aplicaciones de investigación, sigue las prácticas de calidad de fuente en web scraping para investigación en línea. Un fragmento de búsqueda puede identificar un recurso candidato; no es un sustituto para verificar las afirmaciones del recurso. Mantén visibles las observaciones fallidas o caducadas para que los agentes aguas abajo puedan abstenerse en lugar de inventar resultados actuales.
P: ¿Puedo recuperar resultados de búsqueda públicos de YouTube sin OAuth?
El ejemplo de búsqueda pública utiliza una clave de API. Las operaciones que implican datos de usuario autorizados pueden requerir OAuth y permisos adicionales; sigue la documentación actual del método.
P: ¿La API reproducirá mi página de búsqueda de YouTube?
No. Trátalo como resultados de una solicitud de API documentada con parámetros registrados, no como una copia de rankings de navegador personalizados o características de búsqueda visual.
P: ¿Puede Nstdata Crawl reemplazar la API de Datos de YouTube?
No. Usa Crawl para contenido web externo aprobado en el flujo de trabajo circundante. No reemplaza las credenciales de la API de YouTube, las cuotas o los requisitos de política.
P: ¿Una página vacía prueba que no existen videos coincidentes?
No. Interprétalo dentro del contexto de solicitud y respuesta. Valida los filtros y la paginación, preserva la observación y evita afirmar una cobertura completa de la plataforma.
Utiliza la API oficial de YouTube Data para la recopilación de búsqueda pública limitada con filtros explícitos y procedencia. Sigue ejemplos de Python y curl, diagnostica fallos y mantiene el contexto web externo separado.
Ivy Lin
Nov. 16th 2026
Rastrea sitios web completos con una sola solicitud API
99,8% de éxito con renderizado JavaScript
Obtén datos limpios, listos para LLM, en múltiples formatos
Convierte cualquier sitio web en Markdown, HTML, JSON, enlaces, PDF y más, sin gestionar infraestructura de rastreo.