Reports: Query

Importante: Las solicitudes a la API para este método ahora requieren acceso al alcance https://www.googleapis.com/auth/youtube.readonly.

Este método te permite recuperar muchos informes diferentes de Analytics. Cada solicitud usa parámetros de consulta para especificar un ID de canal o un propietario del contenido, una fecha de inicio, una fecha de finalización y, al menos, una métrica. También puedes proporcionar parámetros de consulta adicionales, como instrucciones de orden, dimensiones y filtros.

  • Métricas: medidas individuales de la actividad del usuario, como las reproducciones o calificaciones ("me gusta" y "no me gusta") de los videos.
  • Dimensiones: criterios comunes que se utilizan para recopilar datos, como la fecha en que se produjo la actividad de los usuarios o el país donde se encuentran los usuarios. En un informe, cada fila de datos tiene una combinación única de valores de dimensiones.
  • Filtros: valores de dimensión que especifican los datos que se recuperarán. Por ejemplo, puedes recuperar datos para un país específico, un video específico o un grupo de videos.

Nota: Los informes de propietarios de contenido solo están disponibles para los socios de contenido de YouTube que participan en el Programa de socios de YouTube.

Casos de uso habituales

Solicitud

Solicitud HTTP

GET https://youtubeanalytics.googleapis.com/v2/reports

Todas las solicitudes a la API de YouTube Analytics deben estar autorizadas. La guía de autorización explica cómo usar el protocolo OAuth 2.0 para recuperar tokens de autorización.

Las solicitudes a la API de YouTube Analytics usan los siguientes alcances de autorización:

Permisos
https://www.googleapis.com/auth/yt-analytics.readonly Permite ver informes de YouTube Analytics sobre tu contenido de YouTube. Este alcance proporciona acceso a las métricas de actividad del usuario, como el número de reproducciones y de calificaciones.
https://www.googleapis.com/auth/yt-analytics-monetary.readonly Permite ver informes monetarios de YouTube Analytics sobre tu contenido de YouTube. Este permiso proporciona acceso a las métricas de actividad del usuario, así como a las métricas estimadas de ingresos y rendimiento de los anuncios.
https://www.googleapis.com/auth/youtube Permite administrar tu cuenta de YouTube. En la API de YouTube Analytics, los propietarios de canales usan este alcance para administrar grupos y elementos de grupo de YouTube Analytics.
https://www.googleapis.com/auth/youtubepartner Ver y administrar los activos y el contenido asociado de YouTube en la plataforma En la API de YouTube Analytics, los propietarios del contenido usan este alcance para administrar grupos y elementos de grupo de YouTube Analytics.

Parámetros

Las siguientes tablas enumeran los parámetros de consulta obligatorios y opcionales para las solicitudes a la API para recuperar informes de consultas. Los parámetros de consulta estándar enumerados en la tabla también son opcionales y son compatibles con muchas APIs de Google.

Parámetros
Parámetros obligatorios
endDate string
La fecha de finalización para recuperar los datos de YouTube Analytics. El valor debe tener el formato YYYY-MM-DD.

La respuesta de la API contiene datos hasta el último día. Todas las métricas de la consulta están disponibles en el momento en que se realizó la consulta. Por ejemplo, si la solicitud especifica la fecha de finalización el 5 de julio de 2017 y los valores de todas las métricas solicitadas solo están disponibles hasta el 3 de julio de 2017, esa será la última fecha para la que se incluirán datos en la respuesta. Esto es así incluso si los datos de algunas de las métricas solicitadas están disponibles para el 4 de julio de 2017.
Nota: En la versión 1 de la API, este parámetro se llamaba end-date.
ids string
Identifica el canal de YouTube o el propietario del contenido del que quieres recuperar datos de YouTube Analytics.

  • Para solicitar datos de un canal de YouTube, establece el valor del parámetro ids en channel==MINE o channel==CHANNEL_ID, donde CHANNEL_ID identifica el canal de YouTube del usuario autenticado actualmente.
  • Para solicitar datos de un propietario del contenido de YouTube, establece el valor del parámetro ids en contentOwner==OWNER_NAME, donde OWNER_NAME es el content owner ID del usuario.

metrics string
Una lista separada por comas de métricas YouTube Analytics, como views o likes,dislikes. Consulta la documentación sobre los informes de canales o los informes de propietarios de contenido para obtener una lista de los informes que puedes recuperar y las métricas disponibles en cada uno. (El documento Métricas contiene definiciones para todas las métricas).
startDate string
Fecha de inicio para recuperar los datos de YouTube Analytics. El valor debe tener el formato YYYY-MM-DD.
Nota: En la versión 1 de la API, este parámetro se llamaba start-date.
Parámetros opcionales
currency string
Es la moneda que usará la API para especificar las siguientes métricas de ingresos estimados: estimatedRevenue, estimatedAdRevenue, estimatedRedPartnerRevenue, grossRevenue, cpm y playbackBasedCpm. Los valores que muestra la API para esas métricas son estimaciones calculadas a partir de tipos de cambio que cambian a diario. Si no se solicita ninguna de esas métricas, se ignora el parámetro.

El valor del parámetro es un código de moneda ISO 4217 de tres letras de la lista de monedas a continuación. La API muestra un error si se especifica una moneda no admitida. El valor predeterminado es USD.
dimensions string
Es una lista separada por comas de las dimensiones de YouTube Analytics, como video o ageGroup,gender. Consulta la documentación sobre los informes de canales o los informes de propietarios de contenido para obtener una lista de los informes que puedes recuperar y las dimensiones que se utilizan para ellos. (El documento Dimensiones contiene definiciones para todas las dimensiones).
filters string
Lista de los filtros que se deben aplicar cuando se recuperan los datos de YouTube Analytics. En la documentación de los informes de canales y los informes de propietarios de contenido, se identifican las dimensiones que se pueden usar para filtrar cada informe, y el documento Dimensiones las define.

Si una solicitud usa varios filtros, únelos con un punto y coma (;), y la tabla de resultados que se muestre cumplirá con ambos filtros. Por ejemplo, un valor del parámetro filters de video==dMH0bHeiRNg;country==IT restringe el conjunto de resultados para incluir los datos del video específico en Italia.

Especificar varios valores para un filtro

La API admite la capacidad de especificar varios valores para los filtros video, playlist y channel. Para hacerlo, especifica una lista separada de los ID de video, playlist o canal para los que se debe filtrar la respuesta de la API. Por ejemplo, un valor del parámetro filters de video==pd1FJh59zxQ,Zhawgd0REhA;country==IT restringe el conjunto de resultados para incluir los datos de los videos especificados en Italia. El valor del parámetro puede especificar hasta 500 IDs.

Cuando especificas varios valores para el mismo filtro, también puedes agregar ese filtro a la lista de dimensiones que especificas para la solicitud. Esto se aplica incluso si el filtro no aparece como una dimensión admitida para un informe en particular. Si agregas el filtro a la lista de dimensiones, la API también utiliza los valores del filtro para agrupar los resultados.

Por ejemplo, supongamos que recuperas el informe de fuentes de tráfico de un canal, que agrega estadísticas de vistas según la forma en que los usuarios llegaron al contenido de video del canal. Supongamos también que la solicitud del parámetro filters de tu solicitud identifica una lista de 10 videos de los que se deben mostrar datos.
  • Si agregas video al valor del parámetro dimensions, la respuesta de la API proporcionará estadísticas de la fuente de tráfico independientes para cada uno de los 10 videos.
  • Si no agregas video al valor del parámetro dimensions, la respuesta de la API agregará las estadísticas de las fuentes de tráfico de los 10 videos.
includeHistoricalChannelData boolean
Nota: Este parámetro solo se aplica a los informes de propietarios de contenido.

Indica si la respuesta de la API debe incluir el tiempo de reproducción y los datos de vistas del canal desde el período anterior a la vinculación del canal con el propietario del contenido. El valor del parámetro predeterminado es false, lo que significa que la respuesta de la API solo incluye el tiempo de reproducción y los datos de visualización de las fechas en que los canales se vincularon con el propietario del contenido.

Es importante recordar que es posible que varios canales se hayan vinculado a un propietario del contenido en diferentes fechas. Si la solicitud a la API recupera datos de varios canales y el valor del parámetro es false, la respuesta de la API contendrá datos basados en la fecha de vinculación para cada canal respectivo. Si el valor del parámetro es true, la respuesta de la API contiene datos que coinciden con las fechas especificadas en la solicitud a la API.
Nota: En la versión 1 de la API, este parámetro se llamaba include-historical-channel-data.
maxResults integer
La cantidad máxima de filas que se deben incluir en la respuesta.
Nota: En la versión 1 de la API, este parámetro se llamaba max-results.
sort string
Una lista de dimensiones o métricas separadas por comas que determinan el orden de los datos de YouTube Analytics. El orden de clasificación predeterminado es ascendente El prefijo - genera un orden descendente.
startIndex integer
Es el índice basado en 1 de la primera entidad que se recuperará. El valor predeterminado es 1. Usa este parámetro como un mecanismo de paginación junto con el parámetro max-results.
Nota: En la versión 1 de la API, este parámetro se llamaba start-index.
Parámetros estándar
access_token Token OAuth 2.0 para el usuario actual.
alt Este parámetro no es compatible con la versión 2 de la API, que solo admite respuestas JSON.El formato de datos para la respuesta de la API.
  • Valores válidos: json, csv
  • Valor predeterminado: json
callback Función de devolución de llamada
  • Nombre de la función de devolución de llamada de JavaScript que maneja la respuesta
  • Se usa en las solicitudes JSON-P de JavaScript.
prettyPrint

Muestra una respuesta con sangrías y saltos de línea.

  • Muestra la respuesta en un formato legible si es true.
  • Valor predeterminado: true.
  • Cuando el valor es false, se puede reducir el tamaño de la carga útil de la respuesta, lo que podría mejorar el rendimiento en algunos entornos.
quotaUser Este parámetro era compatible con la versión 1 de la API, que dejó de estar disponible. Este parámetro no es compatible con la versión 2 de la API.
userIp Este parámetro era compatible con la versión 1 de la API, que dejó de estar disponible. Este parámetro no es compatible con la versión 2 de la API.

Cuerpo de la solicitud

No envíes el cuerpo de la solicitud cuando llames a este método.

Respuesta

Como se indica en la definición del parámetro alt, la API puede mostrar respuestas en formato JSON o CSV. La información sobre el cuerpo de la respuesta para cada tipo se muestra a continuación:

JSON
{
  "kind": "youtubeAnalytics#resultTable",
  "columnHeaders": [
    {
      "name": string,
      "dataType": string,
      "columnType": string
    },
    ... more headers ...
  ],
  "rows": [
    [
      {value}, {value}, ...
    ]
  ]
}
Propiedades
kind string
Este valor especifica el tipo de datos incluidos en la respuesta de la API. Para el método query, el valor de la propiedad kind será youtubeAnalytics#resultTable. Sin embargo, si la API agrega compatibilidad con otros métodos, las respuestas de la API para esos métodos pueden introducir otros valores de la propiedad kind.
columnHeaders[] list
Este valor especifica la información sobre los datos que se muestran en los campos rows. Cada elemento de la lista columnHeaders identifica un campo que se muestra en el valor rows, que contiene una lista de datos separados por comas.

La lista columnHeaders comienza con las dimensiones especificadas en la solicitud a la API, seguidas por las métricas especificadas en la solicitud a la API. El orden de las dimensiones y métricas coincide con el orden de la solicitud a la API.

Por ejemplo, si la solicitud a la API contiene los parámetros dimensions=ageGroup,gender&metrics=viewerPercentage, la respuesta de la API muestra columnas en este orden: ageGroup,gender,viewerPercentage.
columnHeaders[].name string
Es el nombre de la dimensión o métrica.
columnHeaders[].columnType string
Es el tipo de la columna (DIMENSION o METRIC).
columnHeaders[].dataType string
El tipo de datos de la columna (STRING, INTEGER, FLOAT, etc.).
rows[] list
La lista contiene todas las filas de la tabla de resultados. Cada elemento de la lista es una matriz que contiene datos separados por comas que corresponden a una sola fila de datos. El orden de los campos de datos separados por comas coincidirá con el orden de las columnas que aparecen en el campo columnHeaders.

Si no hay datos disponibles para la búsqueda determinada, se omitirá el elemento rows de la respuesta.

La respuesta para una consulta con la dimensión day no contendrá filas correspondientes a los últimos días.

CSV
day, views, likes, ...
"2012-01-01", 12.0, 3, ...
"2012-01-02", 16.0, 2, ...
"2012-01-03", 18.0, 8, ...
...

Ejemplos

Nota: Es posible que las siguientes muestras de código no representen todos los lenguajes de programación admitidos. Consulta la documentación de bibliotecas cliente para obtener una lista de los lenguajes admitidos.

JavaScript

En este ejemplo, se llama a la API de YouTube Analytics para recuperar las vistas diarias y otras métricas del canal del usuario autorizado por el año calendario 2017. En la muestra se utiliza la biblioteca cliente de JavaScript de las APIs de Google.

Antes de ejecutar esta muestra de manera local por primera vez, debes configurar las credenciales de autorización de tu proyecto:
  1. Crea o selecciona un proyecto en la Consola de APIs de Google.
  2. Habilita la API de YouTube Analytics para tu proyecto.
  3. En la parte superior de la página Credenciales, selecciona la pestaña Pantalla de consentimiento de OAuth. Selecciona una dirección de correo electrónico, ingresa un nombre del producto, si aún no lo has hecho, y haz clic en el botón Guardar.
  4. En la página Credenciales, haz clic en el botón Crear credenciales y selecciona ID de cliente de OAuth.
  5. Selecciona el tipo de aplicación Aplicación web.
  6. En el campo Orígenes autorizados de JavaScript, ingresa la URL desde la que publicarás la muestra de código. Por ejemplo, puedes usar algo como http://localhost:8000 o http://yourserver.example.com. Puedes dejar en blanco el campo URIs de redireccionamiento autorizados.
  7. Haz clic en el botón Crear para terminar de crear tus credenciales.
  8. Antes de cerrar el cuadro de diálogo, copia el ID de cliente, que deberás colocar en la muestra de código.

Luego, guarda la muestra en un archivo local. En la muestra, busca la siguiente línea y reemplaza YOUR_CLIENT_ID por el ID de cliente que obtuviste cuando configuraste tus credenciales de autorización.

gapi.auth2.init({client_id: 'YOUR_CLIENT_ID'});

Ahora, ya puedes probar la muestra:

  1. Abre el archivo local desde un navegador web y, luego, abre la consola de depuración en el navegador. Deberías ver una página que muestra dos botones.
  2. Haz clic en el botón autorizar y cargar para iniciar el flujo de autorización del usuario. Si autorizas que la app recupere los datos de tu canal, deberías ver las siguientes líneas impresas en la consola en el navegador: 
    Sign-in successful
GAPI client loaded for API
  3. Si ves un mensaje de error en lugar de las líneas anteriores, confirma que estás cargando la secuencia de comandos desde el URI de redireccionamiento autorizado que configuraste para tu proyecto y que colocaste tu ID de cliente en el código como se describió anteriormente.
  4. Haz clic en el botón execute para llamar a la API. Deberías ver un objeto response impreso en la consola del navegador. En ese objeto, se asigna la propiedad result a un objeto que contiene los datos de la API.
<script src="https://apis.google.com/js/api.js"></script>
<script>
  function authenticate() {
    return gapi.auth2.getAuthInstance()
        .signIn({scope: "https://www.googleapis.com/auth/yt-analytics.readonly"})
        .then(function() { console.log("Sign-in successful"); },
              function(err) { console.error("Error signing in", err); });
  }
  function loadClient() {
    return gapi.client.load("https://youtubeanalytics.googleapis.com/$discovery/rest?version=v2")
        .then(function() { console.log("GAPI client loaded for API"); },
              function(err) { console.error("Error loading GAPI client for API", err); });
  }
  // Make sure the client is loaded and sign-in is complete before calling this method.
  function execute() {
    return gapi.client.youtubeAnalytics.reports.query({
      "ids": "channel==MINE",
      "startDate": "2017-01-01",
      "endDate": "2017-12-31",
      "metrics": "views,estimatedMinutesWatched,averageViewDuration,averageViewPercentage,subscribersGained",
      "dimensions": "day",
      "sort": "day"
    })
        .then(function(response) {
                // Handle the results here (response.result has the parsed body).
                console.log("Response", response);
              },
              function(err) { console.error("Execute error", err); });
  }
  gapi.load("client:auth2", function() {
    gapi.auth2.init({client_id: 'YOUR_CLIENT_ID'});
  });
</script>
<button onclick="authenticate().then(loadClient)">authorize and load</button>
<button onclick="execute()">execute</button>

yt_analytics_v2.html

Python

En este ejemplo, se llama a la API de YouTube Analytics para recuperar las vistas diarias y otras métricas del canal del usuario autorizado por el año calendario 2017. En la muestra, se usa la biblioteca cliente de Python de las API de Google.

Antes de ejecutar esta muestra de manera local por primera vez, debes configurar las credenciales de autorización de tu proyecto:
  1. Crea o selecciona un proyecto en la Consola de APIs de Google.
  2. Habilita la API de YouTube Analytics para tu proyecto.
  3. En la parte superior de la página Credenciales, selecciona la pestaña Pantalla de consentimiento de OAuth. Selecciona una dirección de correo electrónico, ingresa un nombre del producto, si aún no lo has hecho, y haz clic en el botón Guardar.
  4. En la página Credenciales, haz clic en el botón Crear credenciales y selecciona ID de cliente de OAuth.
  5. Selecciona el tipo de aplicación Other, ingresa el nombre "YouTube Analytics API quickstart" y haz clic en el botón Crear.
  6. Haz clic en OK para descartar el diálogo resultante.
  7. Haz clic en el botón (Descargar JSON) a la derecha del ID de cliente.
  8. Mueve el archivo descargado a tu directorio de trabajo.

También deberás instalar la biblioteca cliente de las APIs de Google para Python y algunas bibliotecas adicionales:

pip install --upgrade google-api-python-client
pip install --upgrade google-auth google-auth-oauthlib google-auth-httplib2

Ahora, ya puedes probar la muestra:

  1. Copia la siguiente muestra de código en tu directorio de trabajo.
  2. En la muestra, actualiza el valor de la variable CLIENT_SECRETS_FILE para que coincida con la ubicación del archivo que descargaste después de configurar tus credenciales de autorización.
  3. Ejecuta el código de muestra en una ventana de terminal: 
    python yt_analytics_v2.py
  4. Completa el flujo de autorización. Es posible que el flujo de Auth se cargue automáticamente en tu navegador o que debas copiar la URL de Auth en una ventana del navegador. Al final del flujo de autorización, si es necesario, pega en la ventana de tu terminal el código de autorización que se muestra en el navegador y haz clic en [return].
  5. Se ejecuta la consulta de la API y la respuesta JSON se envía a la ventana de terminal.
# -*- coding: utf-8 -*-

import os
import google.oauth2.credentials
import google_auth_oauthlib.flow
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError
from google_auth_oauthlib.flow import InstalledAppFlow

SCOPES = ['https://www.googleapis.com/auth/yt-analytics.readonly']

API_SERVICE_NAME = 'youtubeAnalytics'
API_VERSION = 'v2'
CLIENT_SECRETS_FILE = 'YOUR_CLIENT_SECRET_FILE.json'
def get_service():
  flow = InstalledAppFlow.from_client_secrets_file(CLIENT_SECRETS_FILE, SCOPES)
  credentials = flow.run_console()
  return build(API_SERVICE_NAME, API_VERSION, credentials = credentials)

def execute_api_request(client_library_function, **kwargs):
  response = client_library_function(
    **kwargs
  ).execute()

  print(response)

if __name__ == '__main__':
  # Disable OAuthlib's HTTPs verification when running locally.
  # *DO NOT* leave this option enabled when running in production.
  os.environ['OAUTHLIB_INSECURE_TRANSPORT'] = '1'

  youtubeAnalytics = get_service()
  execute_api_request(
      youtubeAnalytics.reports().query,
      ids='channel==MINE',
      startDate='2017-01-01',
      endDate='2017-12-31',
      metrics='estimatedMinutesWatched,views,likes,subscribersGained'
      dimensions='day',
      sort='day'
  )

yt_analytics_v2.py

Pruébalo

Usa APIs Explorer para llamar a esta API y ver la solicitud y la respuesta a la API.