Su sitio necesita un feed de vídeos de YouTube, pero no existe un plugin listo para esa tarea y usted ya se imagina una semana lidiando con OAuth, tokens y librerías engorrosas. La API de datos de YouTube v3 resuelve este trabajo en aproximadamente una hora. Sin OAuth, sin tokens de usuario, sin dependencias externas. Solo una clave de API y una URL correctamente construida.

El endpoint de búsqueda devuelve vídeos, canales y listas de reproducción por palabras clave. Filtra por fecha, duración y canal. Ordena por relevancia o número de visualizaciones. En la práctica, esto cubre la mayoría de los escenarios, desde el feed de vídeos de un canal específico hasta una recopilación de tutoriales de «wordpress» del último mes.

A continuación encontrará una guía paso a paso con ejemplos de solicitudes en vivo y código PHP. Al finalizar, tendrá un módulo de búsqueda funcional: JSON estructurado de entrada, galería de vídeos de salida, cero librerías de terceros.

💡 Resumen rápido:

• Cree un proyecto en la consola de Google Cloud, habilite la API de datos de YouTube v3 y obtenga una clave de API.
• Construya la URL de solicitud de búsqueda: endpoint /youtube/v3/search, parámetros obligatorios part=snippet, key y q (desde junio de 2025 q es obligatorio; sin él, la API devuelve un array vacío).
• Añada filtros: type (video/channel/playlist), channelId, publishedAfter/publishedBefore, maxResults, order, videoDuration, videoEmbeddable.
• Ejecute la solicitud mediante cURL en PHP, analice la respuesta JSON, muestre los resultados y configure la caché mediante transients de WordPress.

Paso 1: Obtener su clave de API

Sin clave, no sale ninguna solicitud a la API. La clave está vinculada a un proyecto en la consola de Google Cloud e identifica su aplicación; no se requiere nada más complicado que iniciar sesión con una cuenta de Google.

Esto es lo que debe hacer:

• Abra la consola de Google Cloud y cree un proyecto nuevo o seleccione uno existente.
• Vaya a APIs y servicios → Biblioteca, busque «YouTube Data API v3» y haga clic en Habilitar.
• Abra APIs y servicios → Credenciales, haga clic en Crear credenciales → Clave de API.
• Copie la clave. Inmediatamente establezca una restricción: Restringir clave → YouTube Data API v3, para que la clave no pueda usarse en otros servicios de Google.

La clave tiene un aspecto similar a la cadena AIzaSyD-... y se pasa en cada solicitud mediante el parámetro key. Para la búsqueda de vídeos públicos, esto es suficiente; no necesita OAuth. Sin embargo, si planea realizar solicitudes en nombre de un usuario (subida de vídeos, gestión de listas de reproducción), necesitará OAuth 2.0.

Prueba rápida: envíe una solicitud GET al endpoint search con cualquier término de búsqueda. Si recibe JSON con un array items, la clave funciona.

Paso 2: URL de solicitud de búsqueda y parámetros obligatorios

Endpoint para la búsqueda:

1
GET https://www.googleapis.com/youtube/v3/search

Dos parámetros son siempre obligatorios:

El parámetro q acepta texto libre, igual que la barra de búsqueda de youtube.com. Puede pasar varias palabras separadas por espacios o signos más: q=wordpress+speed+optimization. Las mayúsculas y minúsculas no importan.

Solicitud mínima funcional:

1
https://www.googleapis.com/youtube/v3/search?part=snippet&q=wordpress&key=YOUR_KEY

Devolverá 5 resultados (el valor predeterminado), que es lo que la API devuelve cuando no se sobrescribe maxResults.

El parámetro type acota el tipo de recurso que se busca:

• video, solo vídeos;
• channel, solo canales;
• playlist, solo listas de reproducción.

Puede listar varios valores separados por comas: type=video,channel. Si se omite, la API busca en todo. Los parámetros restantes son opcionales, pero convierten una consulta genérica en una herramienta precisa.

Paso 3: Buscar vídeos por palabras clave

Un escenario clásico: un usuario introduce una frase de búsqueda en su sitio, usted la envía a la API de YouTube y muestra una selección de vídeos.

Ejemplo de solicitud para buscar vídeos con la palabra «swimming»:

1
https://www.googleapis.com/youtube/v3/search?part=snippet&q=swimming&type=video&key=YOUR_KEY

La respuesta llega en JSON. Dentro de items[] hay un array de recursos encontrados. Para cada vídeo dispone de:

• id.videoId, el identificador único (se inserta en https://www.youtube.com/watch?v=...);
• snippet.title, el título del vídeo;
• snippet.description, la descripción;
• snippet.thumbnails, vistas previas en varias resoluciones (default, medium, high);
• snippet.channelTitle, el nombre del canal.

En PHP, la forma más sencilla de obtener la respuesta es mediante file_get_contents. Aquí tiene un código de procesamiento mínimo:

1
$apiKey = 'YOUR_KEY';
2
$query  = 'swimming';
3
$url    = "https://www.googleapis.com/youtube/v3/search?part=snippet&q={$query}&type=video&key={$apiKey}";
4
 
5
$response = file_get_contents($url);
6
$data     = json_decode($response, true);
7
 
8
foreach ($data['items'] as $item) {
9
    echo '<h3>' . htmlspecialchars($item['snippet']['title']) . '</h3>';
10
    echo '<p>' . htmlspecialchars($item['snippet']['description']) . '</p>';
11
    echo '<img src="' . $item['snippet']['thumbnails']['medium']['url'] . '" alt="">';
12
    echo '<a href="https://www.youtube.com/watch?v=' . $item['id']['videoId'] . '">Watch</a>';
13
}

file_get_contents está bien para pruebas y proyectos pequeños. En producción, use cURL: le da control sobre tiempos de espera, cabeceras y manejo de errores. Y sí, si allow_url_fopen está deshabilitado en su alojamiento, file_get_contents no funcionará para URLs externas. En ese caso, cURL es su única opción.

Paso 4: Obtener vídeos de un canal específico

Para recopilar todos los vídeos de un canal, pase el parámetro channelId. Encontrar el identificador del canal es fácil: abra la página del canal en YouTube y copie el valor después de /channel/ de la barra de direcciones (por ejemplo UC3VyA8KN_VgCF93EurnAQXw).

Solicitud:

1
https://www.googleapis.com/youtube/v3/search?part=snippet&channelId=UC3VyA8KN_VgCF93EurnAQXw&type=video&order=date&key=YOUR_KEY

El parámetro order=date ordena por fecha de publicación, primero los más recientes. Sin él, la API devuelve los resultados más relevantes, pero para el feed de un canal tiene más sentido el orden cronológico.

La misma solicitud en PHP con cURL y manejo básico de errores:

1
$apiKey    = 'YOUR_KEY';
2
$channelId = 'UC3VyA8KN_VgCF93EurnAQXw';
3
$url       = "https://www.googleapis.com/youtube/v3/search?part=snippet&channelId={$channelId}&type=video&order=date&key={$apiKey}";
4
 
5
$ch = curl_init();
6
curl_setopt_array($ch, [
7
    CURLOPT_URL            => $url,
8
    CURLOPT_RETURNTRANSFER => true,
9
    CURLOPT_TIMEOUT        => 15,
10
    CURLOPT_SSL_VERIFYPEER => true,
11
]);
12
 
13
$response = curl_exec($ch);
14
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
15
curl_close($ch);
16
 
17
if ($httpCode !== 200) {
18
    echo 'Request error. Code: ' . $httpCode;
19
    exit;
20
}
21
 
22
$data = json_decode($response, true);
23
 
24
foreach ($data['items'] as $item) {
25
    printf(
26
        '<div><a href="https://www.youtube.com/watch?v=%s">%s</a></div>',
27
        $item['id']['videoId'],
28
        htmlspecialchars($item['snippet']['title'])
29
    );
30
}

Un canal puede tener cientos de vídeos, pero una sola solicitud no devuelve más de 50. Para obtenerlos todos, use el campo pageToken de la respuesta de la API: pase su valor en la siguiente solicitud como pageToken=<token>. Repita hasta que nextPageToken esté vacío.

Paso 5: Límites, ordenación y cuotas

En un sitio real, rara vez necesita «todos los vídeos de una consulta». Lo más frecuente es que quiera los 10 mejores del último mes o una selección que excluya los Shorts. Para ello, la API proporciona cinco parámetros de ajuste fino.

maxResults: cuántos elementos devolver. Valores válidos: de 1 a 50. El valor predeterminado es 5. Para una galería o feed, establezca 20-30, pero tenga en cuenta las cuotas.

order: campo de ordenación:

publishedAfter** / **publishedBefore: filtrar por fecha de publicación. Formato: ISO 8601 (RFC 3339). Ejemplo: publishedAfter=2026-01-01T00:00:00Z. Descarta vídeos archivados cuando solo necesita contenido fresco.

videoDuration: filtrar por duración:

• short, menos de 4 minutos;
• medium, de 4 a 20 minutos;
• long, más de 20 minutos;
• no especificado, todos.

videoEmbeddable con valor true selecciona solo vídeos que permiten la inserción en sitios de terceros. Para un sitio que incrusta el reproductor de YouTube, este es un parámetro obligatorio.

Solicitud combinada: 10 vídeos insertables sobre WordPress, no anteriores a 2026, de más de 4 minutos, ordenados por número de visualizaciones:

1
https://www.googleapis.com/youtube/v3/search?part=snippet&q=wordpress+tutorial&type=video&videoEmbeddable=true&videoDuration=medium&publishedAfter=2026-01-01T00:00:00Z&maxResults=10&order=viewCount&key=YOUR_KEY

Cuotas: cómo evitar una pantalla en blanco

Cada llamada a search.list cuesta 100 unidades de su cuota diaria. Por defecto, un proyecto de Google Cloud recibe 10 000 unidades diarias gratuitas, aproximadamente 100 llamadas de búsqueda. Para un sitio con más de cien visitantes al día, eso no es suficiente.

La solución es almacenar en caché las respuestas de la API. En WordPress, los transients funcionan perfectamente para esto:

1
$cache_key = 'yt_search_' . md5($query);
2
$videos    = get_transient($cache_key);
3
 
4
if ($videos === false) {
5
    $response = wp_remote_get($url);
6
    $body     = json_decode(wp_remote_retrieve_body($response), true);
7
    $videos   = $body['items'] ?? [];
8
 
9
    set_transient($cache_key, $videos, 6 * HOUR_IN_SECONDS);
10
}
11
 
12
// Display $videos in a gallery...

Un transient de seis horas significa un máximo de 4 solicitudes a la API por día para una única frase de búsqueda. Incluso con diez consultas diferentes en las páginas del sitio, se mantiene por debajo de 40 llamadas, menos de la mitad de la cuota diaria. Si necesita más, solicite un aumento de cuota a través de la consola de Google Cloud: Cuotas → YouTube Data API v3 → Editar.

El ejemplo en vivo anterior muestra cómo construir una galería de vídeos de un canal mediante la API de datos v3 en PHP en 15 minutos.

⁉️🤔 Preguntas frecuentes

¿Se necesita OAuth para buscar vídeos a través de la API de YouTube?

No. Para las solicitudes de búsqueda a /youtube/v3/search, basta con una clave de API. OAuth solo se requiere para operaciones a nivel de usuario: subir vídeos, gestionar listas de reproducción, suscripciones. Una clave de API se obtiene en la consola de Google Cloud en un par de minutos y se usa de inmediato.

¿Cuántas solicitudes gratuitas se pueden hacer al día?

Cada proyecto de Google Cloud recibe 10 000 unidades de cuota diarias gratuitas. Una llamada a search.list cuesta 100 unidades, por lo que son aproximadamente 100 solicitudes de búsqueda al día. Con caché mediante transients de WordPress, esto es suficiente para un sitio medio. Si necesita más, solicite un aumento de cuota a través de la consola de Google Cloud (sección Cuotas).

¿Cómo obtengo más de 50 resultados de una sola consulta?

Mediante paginación. En la respuesta JSON, la API devuelve un campo nextPageToken. Pase su valor como el parámetro pageToken en la siguiente solicitud para obtener la página siguiente. Repita hasta que nextPageToken esté vacío. Un recorrido completo por un canal con 500 vídeos requiere 10 solicitudes y 1000 unidades de cuota.

¿Puedo buscar vídeos en otros idiomas además del inglés?

Sí. El parámetro q acepta cualquier idioma, incluido el ruso. El algoritmo de búsqueda de YouTube determina la relevancia del idioma automáticamente. Para forzar el filtrado, añada el parámetro relevanceLanguage=ru; los resultados se clasificarán favoreciendo el contenido en ruso.

¿Por qué la API devuelve un array vacío aunque la solicitud sea correcta?

La causa más común: publishedAfter está configurado con una fecha futura o con la fecha de hoy con una hora exacta. Use el inicio del día: T00:00:00Z. La segunda causa: una combinación de filtros que excluye todos los resultados. Por ejemplo, videoDuration=long y videoEmbeddable=true junto con el channelId de un canal pequeño puede no arrojar ninguna coincidencia. Simplifique la solicitud hasta part=snippet&q=...&key=... y añada filtros uno a uno, comprobando los resultados en cada paso.

Construir la búsqueda en una hora: qué herramientas se adaptan a cada tarea

Su elección de herramientas depende de qué esté construyendo exactamente. Si necesita una galería de vídeos sencilla para un canal en un sitio de pequeña empresa, utilice un envoltorio PHP ya preparado como madcoda/php-youtube-api: un paquete de Composer, tres líneas de código, resultado en cinco minutos. Si está construyendo una búsqueda personalizada con filtros, caché y paginación, escriba su propio manejador usando cURL más transients de WordPress. Para un sitio de alto tráfico con decenas de miles de visitantes, añada una capa de caché Redis sobre los transients y configure la sincronización en segundo plano mediante WP-Cron; así las páginas cargan en milisegundos y las cuotas de la API se gastan solo en la invalidación de la caché.

Ya tiene su clave de API. La caché está configurada. Solo queda ensamblar la URL para su tarea y escribir el bucle de salida. El resultado es un feed de vídeos en vivo que no depende de servicios de terceros y no agota los límites de cuota.