Reports: Query

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

Este método le permite recuperar muchos informes de Analytics diferentes. Cada solicitud utiliza parámetros de consulta para especificar un ID de canal o un propietario de contenido, una fecha de inicio, una fecha de finalización y, al menos, una métrica. También puede proporcionar parámetros de búsqueda adicionales, como instrucciones para ordenar, filtros y dimensiones.

  • 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 dimensión.
  • Filtros: valores de dimensión que especifican los datos que se recuperarán. Por ejemplo, puedes recuperar los datos de un país, de un video o de un grupo de videos concretos.

Nota: Solo los socios de contenido de YouTube que participan en el Programa de socios de YouTube pueden acceder a los informes de propietarios del contenido.

Casos de uso habituales

Solicitud

Solicitud HTTP

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

Se deben autorizar todas las solicitudes de la API de YouTube Analytics. La Guía de autorización explica cómo utilizar el protocolo OAuth 2.0 para recuperar tokens de autorización.

Las solicitudes de la API de YouTube Analytics utilizan 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 alcance proporciona acceso a las métricas de actividad del usuario y a las estimaciones de ingresos y de 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 utilizan este alcance para administrar grupos de YouTube Analytics y elementos de grupos.
https://www.googleapis.com/auth/youtubepartner Ver y administrar los elementos y contenido asociado en YouTube En la API de YouTube Analytics, los propietarios de contenido utilizan este alcance para administrar grupos de YouTube Analytics y elementos de grupos.

Parámetros

En la siguiente tabla, se enumeran los parámetros de consulta obligatorios y opcionales para las solicitudes a la API a fin de recuperar los informes de consultas. Los parámetros de consulta estándar que aparecen en la tabla también son opcionales y son compatibles con muchas API de Google.

Parámetros
Parámetros obligatorios
endDate string
Es la fecha de finalización para recuperar datos de YouTube Analytics. El valor debe estar en formato YYYY-MM-DD.

La respuesta de la API contiene datos hasta el último día para el que todas las métricas de la consulta están disponibles en el momento de la consulta. Por lo tanto, si la solicitud especifica una fecha de finalización del 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 incluyan datos en la respuesta. (Esto se aplica 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 denominaba end-date.
ids string
Identifica el canal de YouTube o el propietario del contenido para el que deseas recuperar los 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 de contenido de YouTube, establece el valor del parámetro ids en contentOwner==OWNER_NAME, donde OWNER_NAME es content owner ID para el usuario.

metrics string
Una lista separada por comas de métricas de YouTube Analytics, como views o likes,dislikes. Consulta la documentación para informes de canales o informes de propietarios de contenido para obtener una lista de los informes que se pueden recuperar y las métricas disponibles en cada informe. (El documento Métricas contiene las definiciones de todas las métricas).
startDate string
Es la fecha de inicio para recuperar datos de YouTube Analytics. El valor debe estar en formato YYYY-MM-DD.
Nota: En la versión 1 de la API, este parámetro se denominaba start-date.
Parámetros opcionales
currency string
La moneda que usará la API para especificar las siguientes métricas de ingresos estimados: estimatedRevenue, estimatedAdRevenue, estimatedRedPartnerRevenue, gruRevenue, cpm, playbackBasedCpm. Los valores que muestra la API para esas métricas son estimaciones que se calculan con 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
Una lista separada por comas de dimensiones de YouTube Analytics, como video o ageGroup,gender. Consulta la documentación para informes de canales o informes de propietarios de contenido para obtener una lista de los informes que se pueden recuperar, así como las dimensiones que se utilizan para tales informes. (El documento Dimensiones contiene las definiciones de todas las dimensiones).
filters string
Es una lista de filtros que se deben aplicar cuando se recuperan datos de YouTube Analytics. La documentación de los informes de canales y de los informes de propietarios de contenido identifica las dimensiones que se pueden usar para filtrar cada informe. En el documento Dimensiones se definen esas dimensiones.

Si en una solicitud se usan 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 datos del video que figura en Italia.

Especifica 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 ID de videos, listas de reproducción o canales 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 datos de videos específicos en Italia. El valor del parámetro puede especificar hasta 500 ID.

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

Por ejemplo, supongamos que recuperas el informe de fuentes de tráfico de un canal, que recopila estadísticas de reproducción según la forma en la que los espectadores llegaron al contenido de video del canal. También supongamos que la solicitud del parámetro filters de tu solicitud identifica una lista de 10 videos para los que se deben mostrar los datos.
  • Si agregas video al valor del parámetro dimensions, la respuesta de la API proporcionará estadísticas de fuentes 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 fuentes de tráfico para 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 visualización de los canales del período anterior a cuando se vincularon los canales al propietario del contenido. El valor predeterminado del parámetro 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 al propietario del contenido.

Es importante recordar que diferentes canales pueden haberse vinculado a un propietario de contenido en distintas 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 según la fecha de vinculación de 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 denominaba 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 denominaba max-results.
sort string
Es 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
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 denominaba start-index.
Parámetros estándar
access_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, puede reducirse 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 un cuerpo de solicitud cuando llames a este método.

Respuesta

Como se indicó 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 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 de las métricas especificadas en la solicitud a la API. El orden de las dimensiones y las 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
El tipo de columna (DIMENSION o METRIC).
columnHeaders[].dataType string
El tipo de datos en 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 consulta dada, el elemento rows se omitirá de la respuesta.

La respuesta para una consulta con la dimensión day no contendrá filas para 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 los siguientes ejemplos de código no representen todos los lenguajes de programación admitidos. Consulta la documentación sobre bibliotecas cliente para obtener una lista de los lenguajes admitidos.

JavaScript

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

Antes de ejecutar esta muestra de manera local por primera vez, debes configurar las credenciales de autorización para tu proyecto:
  1. Crea o selecciona un proyecto en la Consola de API 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. Seleccione una dirección de correo electrónico, ingrese un nombre de producto (si no lo estableció) y haga 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 entregarás la muestra de código. Por ejemplo, puedes usar http://localhost:8000 o http://yourserver.example.com. Puedes dejar el campo de redireccionamiento autorizados de URI en blanco.
  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 ingresar 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 las credenciales de autorización.

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

Ahora estás listo para probar la muestra:

  1. Abre el archivo local desde un navegador web y 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 a la aplicación a recuperar 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. Haga 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, la propiedad result se asigna 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>

Python

En este ejemplo, se llama a la API de YouTube Analytics para recuperar vistas diarias y otras métricas del canal del usuario autorizado para el año calendario 2017. La muestra 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 para tu proyecto:
  1. Crea o selecciona un proyecto en la Consola de API 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. Seleccione una dirección de correo electrónico, ingrese un nombre de producto (si no lo estableció) y haga 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 Otros, ingresa el nombre "YouTube Analytics API Quickstart" y haz clic en el botón Crear.
  6. Haz clic en Aceptar para descartar el cuadro de diálogo resultante.
  7. Haz clic en el botón (Descargar JSON) a la derecha del ID de cliente.
  8. Mueva el archivo descargado al directorio de trabajo.

También debes instalar la biblioteca cliente de las API 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 estás listo para probar la muestra:

  1. Copia la siguiente muestra de código en el 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 las credenciales de autorización.
  3. Ejecuta el código de muestra en una ventana de la terminal:
    python yt_analytics_v2.py
  4. Sigue el proceso de autorización. Es posible que el flujo de Auth se cargue automáticamente en tu navegador o que debas copiar la URL de autenticación en una ventana del navegador. Al final del flujo de autorización, si es necesario, pegue el código de autorización que se muestra en el navegador en la ventana de su terminal y haga clic en [return].
  5. Se ejecuta la consulta de la API y la respuesta JSON se envía a la ventana de la 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'
  )

Pruébela.

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