Descripción general de la API de datos de YouTube

Introducción

Este documento está dirigido a programadores que deseen crear aplicaciones que puedan interactuar con YouTube. En él se explican conceptos básicos de YouTube y de la API. También proporciona una visión general de las diferentes funciones que admite la API.

Antes de comenzar

  1. Necesitas una Cuenta de Google para acceder a la Consola de API de Google, solicitar una clave de API y registrar tu aplicación.

  2. Crea un proyecto en Google Developers Console y obtén credenciales de autorización para que tu aplicación pueda enviar solicitudes a la API.

  3. Después de crear el proyecto, asegúrate de que la API de datos de YouTube sea uno de los servicios para los que está registrada tu aplicación:

    1. Ve a la Consola de API y selecciona el proyecto que acabas de registrar.
    2. Visita la página de APIs habilitadas. En la lista de las APIs, asegúrate de que el estado sea ACTIVADO para la versión 3 de la API de datos de YouTube.

  4. Si tu aplicación va a utilizar cualquier método de API que requiera la autorización del usuario, lee la guía de autenticación para obtener información sobre cómo implementar la autorización OAuth 2.0.

  5. Selecciona una biblioteca cliente para simplificar la implementación de la API.

  6. Aprende los conceptos básicos del formato de datos JSON (JavaScript Object Notation). JSON es un formato de datos común e independiente del lenguaje que proporciona una representación de texto simple de estructuras de datos arbitrarias. Para obtener más información, visita la página json.org.

Recursos y tipos de recursos

Un recurso es una entidad de datos individual con un identificador exclusivo. En la tabla a continuación se describen los distintos tipos de recursos con los que puedes interactuar mediante la API.

Recursos
activity Contiene información sobre una acción que un usuario en particular realizó en el sitio de YouTube. Entre las acciones de los usuarios que se informan en los feeds de actividad se incluyen: calificar videos, compartir videos, marcar un video como favorito, publicar el boletín de un canal, etc.
channel Contiene información sobre un solo canal de YouTube.
channelBanner Identifica la dirección URL que se va a usar para configurar una imagen recién cargada como la imagen de banner de un canal.
channelSection Contiene información sobre un conjunto de videos que un canal eligió destacar. Por ejemplo, una sección puede incluir las cargas más recientes de un canal, las cargas más populares o los videos de una o más listas de reproducción.
guideCategory Identifica una categoría que YouTube asocia con los canales según su contenido u otros indicadores, como la popularidad. El objetivo de las categorías de guía es organizar los canales de una manera que facilite a los usuarios de YouTube encontrar el contenido que buscan. Si bien los canales podrían estar asociados con una o varias categorías de guía, no se garantiza que vayan a estar en alguna de estas categorías.
i18nLanguage Identifica un idioma de aplicación compatible con el sitio web de YouTube. El lenguaje de la aplicación también puede denominarse IU.
i18nRegion Identifica un área geográfica que un usuario de YouTube puede seleccionar como la región de contenido preferida. La región del contenido también puede denominarse configuración regional del contenido.
playlist Representa una lista de reproducción de YouTube. Una lista de reproducción es una colección de videos que se pueden ver de manera sucesiva y compartir con otros usuarios.
playlistItem Identifica un recurso, como por ejemplo un video, que forma parte de una lista de reproducción. El recurso playlistItem también contiene detalles que explican cómo se utiliza el recurso incluido en la lista de reproducción.
search result Contiene información sobre un video, un canal o una lista de reproducción de YouTube que coincide con los parámetros de búsqueda especificados en una solicitud a la API. Si bien un resultado de la búsqueda apunta a un recurso identificable de manera inequívoca, como un video, no tiene sus propios datos persistentes.
subscription Contiene información sobre la suscripción de un usuario de YouTube. Una suscripción notifica al usuario cuando se agregan nuevos videos a un canal o cuando otro usuario realiza una de varias acciones en YouTube, como subir un video, calificar un video o comentar un video.
thumbnail Identifica imágenes en miniatura asociadas a un recurso.
video Representa un video de YouTube.
videoCategory Identifica una categoría que se asoció o podría asociarse a videos subidos.
watermark Identifica una imagen que se muestra durante las reproducciones de videos de un canal específico. El propietario del canal también puede especificar un canal de destino al que se vincula la imagen, así como detalles de los tiempos que determinan cuándo aparece la marca de agua durante las reproducciones de video y el tiempo que es visible.

Ten en cuenta que, en muchos casos, un recurso contiene referencias a otros recursos. Por ejemplo, la propiedad snippet.resourceId.videoId de un recurso playlistItem identifica un recurso de video que, a su vez, contiene información completa sobre el video. Otro ejemplo es que un resultado de la búsqueda contiene una propiedad videoId, playlistId o channelId que identifica un video, una lista de reproducción o un recurso de canal en particular.

Operaciones admitidas

En la siguiente tabla se muestran los métodos más comunes que la API admite. Algunos recursos también admiten otros métodos que realizan funciones más específicas para esos recursos. Por ejemplo, el método videos.rate asocia la calificación de un usuario con un video, y el método thumbnails.set sube una imagen en miniatura de un video a YouTube y la asocia con un video.

Operations
list Recupera (GET) una lista de cero o más recursos.
insert Crea (POST) un nuevo recurso.
update Modifica (PUT) un recurso existente para reflejar los datos de tu solicitud.
delete Elimina (DELETE) un recurso específico.

Actualmente, la API admite métodos para enumerar cada uno de los tipos de recursos admitidos y, del mismo modo, admite operaciones de escritura para muchos recursos.

En la siguiente tabla se identifican las operaciones admitidas para diferentes tipos de recursos. Las operaciones para insertar, actualizar o eliminar recursos siempre requieren la autorización del usuario. En algunos casos, los métodos list admiten solicitudes tanto autorizadas como no autorizadas. Las solicitudes no autorizadas solo recuperan datos públicos, mientras que las solicitudes autorizadas también pueden recuperar información del usuario autenticado actualmente o información privada.

Operaciones admitidas
list insert update delete
activity
caption
channel
channelBanner
channelSection
comment
commentThread
guideCategory
i18nLanguage
i18nRegion
playlist
playlistItem
search result
subscription
thumbnail
video
videoCategory
watermark

Uso de cuota

YouTube Data API usa una cuota para garantizar que los desarrolladores usen el servicio según lo previsto y no creen aplicaciones que reduzcan injustamente la calidad del servicio o limiten el acceso de otras personas. Todas las solicitudes a la API, incluidas las no válidas, incurren en un costo de cuota de al menos un punto. Puedes encontrar la cuota disponible para tu aplicación en API Console.

Los proyectos que habilitan la API de YouTube Data tienen una asignación de cuota predeterminada de 10,000 unidades por día, una cantidad suficiente para la inmensa mayoría de los usuarios de la API. La cuota predeterminada, que está sujeta a cambios, nos ayuda a optimizar las asignaciones de cuotas y escalar nuestra infraestructura de una manera más significativa para los usuarios de la API. Puedes ver el uso de tu cuota en la página Cuotas de la Consola de API.

Nota: Si alcanzas el límite de la cuota, puedes solicitar una cuota adicional completando el formulario de solicitud de extensión de cuota para los servicios de la API de YouTube.

Calcula el uso de la cuota

Google calcula el uso de la cuota mediante la asignación de un costo a cada solicitud. Los distintos tipos de operaciones tienen diferentes costos de cuota. Por ejemplo:

  • Una operación de lectura que recupera una lista de recursos (canales, videos, listas de reproducción) por lo general cuesta 1 unidad.
  • Una operación de escritura en la que se crea, actualiza o borra un recurso, por lo general, tiene un costo de 50 unidades.
  • Una solicitud de búsqueda cuesta 100 unidades.
  • La carga de un video cuesta 1600 unidades.

En la tabla Costos de cuota para las solicitudes a la API, se muestra el costo de la cuota de cada método de la API. Con estas reglas en mente, puedes estimar la cantidad de solicitudes que tu aplicación podría enviar por día sin exceder tu cuota.

Recursos parciales

La API permite, y requiere, la recuperación de recursos parciales para que las aplicaciones eviten la transferencia, el análisis y el almacenamiento de datos que no son necesarios. Este enfoque también garantiza que la API utilice los recursos de red, CPU y memoria de manera más eficiente.

La API admite dos parámetros de solicitud, que se explican en las siguientes secciones, que te permiten identificar las propiedades del recurso que se deben incluir en las respuestas de la API.

  • El parámetro part identifica grupos de propiedades que se deben mostrar para un recurso.
  • El parámetro fields filtra la respuesta de la API para que solo muestre propiedades específicas dentro de las partes de los recursos solicitadas.

Cómo usar el parámetro part

El parámetro part es obligatorio para cualquier solicitud a la API que recupere o muestre un recurso. El parámetro identifica una o más propiedades de recursos de nivel superior (no anidada) que se deben incluir en una respuesta de la API. Por ejemplo, un recurso video tiene las siguientes partes:

  • snippet
  • contentDetails
  • fileDetails
  • player
  • processingDetails
  • recordingDetails
  • statistics
  • status
  • suggestions
  • topicDetails

Todas estas partes son objetos que contienen propiedades anidadas. Puedes considerar estos objetos como grupos de campos de metadatos que el servidor de la API podría (o no) recuperar. Por lo tanto, el parámetro part requiere que selecciones los componentes de recursos que usa tu aplicación. Este requisito tiene dos propósitos clave:

  • Reducir la latencia evitando que el servidor de la API se dedique a recuperar campos de metadatos que tu aplicación no utiliza.
  • Reducir el uso de ancho de banda al reducir (o eliminar) la cantidad de datos innecesarios que la aplicación podría recuperar.

Con el tiempo, a medida que los recursos agregan más partes, estos beneficios irán en aumento debido a que tu aplicación no solicitará las propiedades nuevas que no admita.

Cómo usar el parámetro fields

El parámetro fields filtra la respuesta de la API, que solo contiene las partes de recursos identificadas en el valor del parámetro part, de modo que la respuesta solo incluya un conjunto específico de campos. El parámetro fields te permite quitar propiedades anidadas de una respuesta de la API y, de esta manera, reducir aún más el uso de ancho de banda. (No se puede usar el parámetro part para filtrar propiedades anidadas de una respuesta).

En las siguientes reglas, se explica la sintaxis compatible para el valor del parámetro fields, que se basa de manera general en la sintaxis de XPath:

  • Usa una lista separada por comas (fields=a,b) para seleccionar varios campos.
  • Usa un asterisco (fields=*) como comodín para identificar todos los campos.
  • Usa paréntesis (fields=a(b,c)) para especificar un grupo de propiedades anidadas que se incluirá en la respuesta de la API.
  • Usa una barra diagonal (fields=a/b) para identificar una propiedad anidada.

En la práctica, estas reglas a menudo permiten que varios valores de parámetros fields diferentes recuperen la misma respuesta de la API. Por ejemplo, si deseas recuperar la ID de elemento de lista de reproducción, el título y la posición de todos los elementos de una lista de reproducción, puedes utilizar cualquiera de los siguientes valores:

  • fields=items/id,playlistItems/snippet/title,playlistItems/snippet/position
  • fields=items(id,snippet/title,snippet/position)
  • fields=items(id,snippet(title,position))

Nota: Al igual que con todos los valores de los parámetros de búsqueda, el valor del parámetro de fields debe estar codificado como URL. Para facilitar la lectura, en los ejemplos de este documento se omite la codificación.

Solicitudes parciales de ejemplo

En los siguientes ejemplos, se muestra cómo puedes usar los parámetros part y fields para asegurarte de que las respuestas de la API solo incluyan los datos que usa tu aplicación:

  1. En el ejemplo 1, se muestra un recurso de video que incluye cuatro partes, además de las propiedades kind y etag.
  2. En el ejemplo 2, se muestra un recurso de video que incluye dos partes, además de las propiedades kind y etag.
  3. En el ejemplo 3, se muestra un recurso de video que incluye dos partes, pero excluye las propiedades kind y etag.
  4. En el ejemplo 4, se muestra un recurso de video que incluye dos partes, pero excluye kind y etag, así como algunas propiedades anidadas en el objeto snippet del recurso.
Ejemplo 1
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &part=snippet,contentDetails,statistics,status

Description: This example retrieves a video resource and identifies several
             resource parts that should be included in the API response.

API response:


{ 
 "kind": "youtube#videoListResponse",
 "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/sDAlsG9NGKfr6v5AlPZKSEZdtqA\"",
 "videos": [
  {
   "id": "7lCDEYXw3mM",
   "kind": "youtube#video",
   "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/iYynQR8AtacsFUwWmrVaw4Smb_Q\"",
   "snippet": { 
    "publishedAt": "2012-06-20T22:45:24.000Z",
    "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "title": "Google I/O 101: Q&A On Using Google APIs",
    "description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.",
    "thumbnails": {
     "default": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg"
     },
     "medium": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg"
     },
     "high": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg"
     }
    },
    "categoryId": "28"
   },
   "contentDetails": {
    "duration": "PT15M51S",
    "aspectRatio": "RATIO_16_9"
   },
   "statistics": {
    "viewCount": "3057",
    "likeCount": "25",
    "dislikeCount": "0",
    "favoriteCount": "17",
    "commentCount": "12"
   },
   "status": {
    "uploadStatus": "STATUS_PROCESSED",
    "privacyStatus": "PRIVACY_PUBLIC"
   }
  }
 ]
}
Ejemplo 2
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &part=snippet,statistics

Description: This example modifies the part parameter value so that the
             contentDetails and status properties are not included
             in the response.

API response:


{ 
 "kind": "youtube#videoListResponse",
 "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/sDAlsG9NGKfr6v5AlPZKSEZdtqA\"",
 "videos": [
  {
   "id": "7lCDEYXw3mM",
   "kind": "youtube#video",
   "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/iYynQR8AtacsFUwWmrVaw4Smb_Q\"",
   "snippet": { 
    "publishedAt": "2012-06-20T22:45:24.000Z",
    "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "title": "Google I/O 101: Q&A On Using Google APIs",
    "description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.",
    "thumbnails": {
     "default": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg"
     },
     "medium": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg"
     },
     "high": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg"
     }
    },
    "categoryId": "28"
   },
   "statistics": {
    "viewCount": "3057",
    "likeCount": "25",
    "dislikeCount": "0",
    "favoriteCount": "17",
    "commentCount": "12"
   }
  }
 ]
}
Ejemplo 3
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &part=snippet,statistics&fields=items(id,snippet,statistics)

Description: This example adds the fields parameter to remove all
             kind and etag properties from the API response.

API response:


{ 
 "videos": [
  {
   "id": "7lCDEYXw3mM",
   "snippet": { 
    "publishedAt": "2012-06-20T22:45:24.000Z",
    "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "title": "Google I/O 101: Q&A On Using Google APIs",
    "description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.",
    "thumbnails": {
     "default": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg"
     },
     "medium": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg"
     },
     "high": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg"
     }
    },
    "categoryId": "28"
   },
   "statistics": {
    "viewCount": "3057",
    "likeCount": "25",
    "dislikeCount": "0",
    "favoriteCount": "17",
    "commentCount": "12"
   }
  }
 ]
}
Ejemplo 4
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &fields=items(id,snippet(channelId,title,categoryId),statistics)&part=snippet,statistics

Description: This example modifies the fields parameter from example 3
             so that in the API response, each video resource's snippet
             object only includes the channelId, title,
             and categoryId properties.

API response:


{ 
 "videos": [
  {
   "id": "7lCDEYXw3mM",
   "snippet": { 
    "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "title": "Google I/O 101: Q&A On Using Google APIs",
    "categoryId": "28"
   },
   "statistics": {
    "viewCount": "3057",
    "likeCount": "25",
    "dislikeCount": "0",
    "favoriteCount": "17",
    "commentCount": "12"
   }
  }
 ]
}

Optimización del rendimiento

Usa ETags

ETags, una parte estándar del protocolo HTTP, permite que las aplicaciones se refieran a una versión específica de un recurso de API en particular. El recurso puede ser un feed completo o un elemento de dicho feed. Esta funcionalidad admite los siguientes casos de uso:

  • Almacenamiento en la memoria caché y recuperación condicional: la aplicación puede almacenar en la memoria caché los recursos de la API y sus ETags. Luego, cuando tu aplicación vuelve a solicitar un recurso almacenado, especifica la ETag asociada con ese recurso. Si el recurso cambió, la API muestra el recurso modificado y la ETag asociada con esa versión del recurso. Si el recurso no cambió, la API muestra una respuesta HTTP 304 (Not Modified), que indica que el recurso no cambió. Tu aplicación puede reducir la latencia y el uso de ancho de banda al servir recursos almacenados en la memoria caché de esta manera.

    Las bibliotecas cliente para las API de Google admiten ETags de maneras distintas. Por ejemplo, la biblioteca cliente de JavaScript admite ETags a través de una lista blanca para encabezados de solicitud permitidos que incluye If-Match y If-None-Match. La lista blanca permite el almacenamiento en la memoria caché del navegador normal, de modo que si la ETag del recurso no cambió, el recurso se puede publicar desde la caché del navegador. Por otro lado, el cliente Obj-C no admite ETags.

  • Protección contra sobrescritura accidental de cambios: las ETags garantizan que los múltiples clientes de la API no sobrescriban accidentalmente los cambios del otro. Al actualizar o eliminar un recurso, tu aplicación puede especificar la ETag del recurso. Si la ETag no coincide con la versión más reciente de ese recurso, se produce un error en la solicitud de la API.

El uso de ETags en tu aplicación aporta varios beneficios:

  • La API responde más rápidamente a las solicitudes de recursos en caché, pero sin cambios, lo que genera una menor latencia y un menor uso de ancho de banda.
  • Tu aplicación no sobrescribirá accidentalmente los cambios en un recurso que se realizaron desde otro cliente de la API.

Google APIs Client Library for JavaScript admite encabezados de solicitud HTTP If-Match y If-None-Match, lo que permite que las ETags funcionen en el contexto de almacenamiento en caché normal del navegador.

Usa gzip

También puedes reducir el ancho de banda necesario para cada respuesta de la API al habilitar la compresión gzip. Aunque tu aplicación va a necesitar tiempo adicional de CPU para descomprimir las respuestas de la API, el beneficio de consumir menos recursos de red suele ser mayor que el costo.

Para recibir una respuesta codificada como gzip debes hacer dos cosas:

  • Establece el encabezado de la solicitud HTTP Accept-Encoding en gzip.
  • Modifica tu usuario-agente para que contenga la string gzip.

Los siguientes encabezados HTTP de ejemplo demuestran estos requisitos para habilitar la compresión gzip:

Accept-Encoding: gzip
User-Agent: my program (gzip)