Getting Started with the YouTube Data API

Introducción

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

Antes de comenzar

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

  2. Registra tu aplicación en Google para que pueda enviar solicitudes de API.

  3. Después de registrar tu aplicación, selecciona la API de datos de YouTube como uno de los servicios que utiliza tu aplicación:

    1. Ve a la consola de la API y selecciona el proyecto que acabas de registrar.
    2. Haz clic en el panel Servicios.
    3. En la lista de las API, busca la API de datos de YouTube y cambia el estado a ON.

  4. 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.
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.
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 Un resultado de búsqueda contiene información acerca de un video, canal o lista de reproducción de YouTube que coincide con los parámetros de búsqueda especificados en una solicitud de la API. Si bien un resultado de búsqueda apunta a un recurso único de identificación, 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.

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 toda la información del video. En otro ejemplo, un resultado de búsqueda contiene una propiedad videoId, playlistId o channelId, que identifica un video, una lista de reproducción o recursos 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 a un video.

Operaciónes
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 un (DELETE) 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 de list admiten solicitudes tanto autorizadas como no autorizadas. Entonces, las solicitudes no autorizadas solo recuperan datos públicos, mientras que las solicitudes autorizadas pueden obtener información pública o privada del usuario autenticado actualmente.

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

La YouTube Data API utiliza una cuota para garantizar que los programadores usen el servicio según lo previsto y no creen aplicaciones que reduzcan injustamente la calidad del servicio o limiten el acceso de las demás personas. Puedes encontrar la cuota disponible para tu aplicación en el panel de API console's Cuotas.

Google calcula el uso de tu cuota mediante la asignación de un costo a cada solicitud, pero el costo no es el mismo para cada solicitud. Hay dos factores principales que influyen en el costo de la cuota de una solicitud:

  1. Diferentes tipos de operaciones tienen diferentes costos de cuotas.

    • Una operación de lectura simple que solo recupera el ID de cada recurso devuelto tiene un costo de aproximadamente 1 unidad.
    • Una operación de escritura tiene un costo de aproximadamente 50 unidades.
    • Subir un video tiene un costo de aproximadamente 1600 unidades.

  2. Las operaciones de lectura y escritura utilizan diferentes cantidades de cuota, según el número de partes de los recursos que recupera cada solicitud. Ten en cuenta que las operaciones insert y update escriben datos y también muestran un recurso. Entonces, por ejemplo, la inserción de una lista de reproducción tiene un costo de cuota de 50 unidades por la operación de escritura más el costo del recurso mostrado de lista de reproducción.

    Como se explica en la sección siguiente, cada recurso de API se divide en partes. Por ejemplo, un recurso de playlist tiene dos partes, snippet y status, mientras que un recurso de channel tiene seis partes y un recurso de video tiene 10. Cada parte contiene un grupo de propiedades relacionadas, y los grupos están diseñados de manera que tu aplicación solo necesita recuperar los tipos de datos que realmente utiliza.

    Una solicitud de API que muestra datos de recursos debe especificar las partes de los recursos que la solicitud recupera. Cada parte agrega aproximadamente 2 unidades al costo de la cuota de la solicitud. Como tal, una solicitud de videos.list que solo recupera la parte snippet de cada video podría tener un costo de 3 unidades. Sin embargo, una solicitud de videos.list que recupera todas las partes de cada recurso podría tener un costo aproximado de 21 unidades de cuota.

Con estas reglas en mente, se puede estimar el número de solicitudes de lectura, escritura o subida que tu aplicación podría enviar al día sin exceder la cuota. Por ejemplo, si tienes una cuota diaria de 5.000.000 de unidades, tu aplicación podría tener cualquiera de los siguientes límites aproximados:

  • 1.000.000 de operaciones de lectura, donde cada una recupera dos partes de recursos.
  • 50.000 operaciones de escritura y 450.000 operaciones de lectura adicionales, donde cada una recupera dos partes de recursos.
  • 2.000 subidas de video, 7.000 operaciones de escritura y 200.000 operaciones de lectura, donde cada una recupera tres partes de recursos.

Importante: La recuperación de solamente las partes de recursos que necesita tu aplicación permite conservar tu cuota diaria y hace que todo el sistema sea más eficiente.

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 permiten identificar las propiedades de los recursos 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 devuelva solo las propiedades específicas dentro de las partes de los recursos solicitados.

Qué es el parámetro part

El parámetro part es obligatorio para cualquier solicitud de API que recupera o muestra 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 de video tiene las siguientes partes:

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

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

  • Te permite administrar el uso de tu cuota de API. Cuando aumenta el número de partes que se recuperan en las respuestas de la API, tu uso de la API aumenta en consecuencia, y tu cuota disponible disminuye.
  • Se reduce la latencia al impedir que el servidor de la API se dedique a recuperar campos de metadatos que tu aplicación no utiliza.
  • Se reduce el uso de ancho de banda al reducir (o eliminar) la cantidad de datos innecesarios que la aplicación puede recuperar.

Con el tiempo, a medida que los recursos agregan más partes, estos beneficios solo aumentan dado que tu aplicación no va a solicitar propiedades recién introducidas que no admite.

Qué es el parámetro fields

El parámetro fields filtra la respuesta de la API, que solo contiene las partes de los recursos identificados en el valor del parámetro part, de modo que la respuesta solo incluye un conjunto específico de campos. El parámetro fields permite eliminar propiedades anidadas de una respuesta de la API para reducir aún más el uso de ancho de banda. (El parámetro part no se puede utilizar para filtrar propiedades anidadas de una respuesta).

Las siguientes reglas explican la sintaxis admitida para el valor del parámetro fields, que se basa libremente 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, a menudo estas normas permiten que diferentes valores del parámetro fields 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 consulta, el valor del parámetro fields debe estar codificado como dirección URL. Para facilitar la lectura, los ejemplos de este documento omiten la codificación.

Solicitudes parciales de ejemplo

En los ejemplos siguientes se muestra cómo se pueden utilizar los parámetros part y fields para garantizar que las respuestas de la API incluyan solo los datos que utiliza la 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 las propiedades kind y etag, además de 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

Descripción: en este ejemplo se recupera un recurso de video y se identifican varias partes de los recursos que se deben incluir en la respuesta de la API.

Respuesta de la API:


{ 
 "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

Descripción: En este ejemplo se modifica el valor del parámetro part para que las propiedades
contentDetails y status no se incluyan en la respuesta.

Respuesta de la API:


{ 
 "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)

Descripción: En este ejemplo se agrega el parámetro fields para eliminar todas las propiedades kind y etag de la respuesta de la API.

Respuesta de la API:


{ 
 "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

Descripción: En este ejemplo se modifica el parámetro fields del ejemplo 3 para que en la respuesta de la API cada objeto snippet del recurso de video incluya solo las propiedades channelId, title y categoryId.

Respuesta de la API:


{ 
 "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

Uso de ETags

Las ETags, parte estándar del protocolo HTTP, permiten que las aplicaciones se refieran a una versión determinada 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), lo 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 JavaScript admite ETags a través de una lista blanca de encabezados de solicitudes permitidas que incluye If-Match e 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.

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

Uso de 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:

  • Establecer el encabezado de solicitud HTTP Accept-Encoding en gzip.
  • Modificar tu agente de usuario para que contenga la unidad gzip.

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

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