Importante: Las solicitudes a la API para este método ahora requieren acceso al alcance de 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 dimensiones, filtros y las instrucciones de ordenamiento.
- 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, podrías recuperar datos de un país específico, un video específico o un grupo de videos.
Nota: Solo los socios de contenido de YouTube que participan en el Programa de socios de YouTube pueden acceder a los informes de propietario del contenido.
Casos de uso habituales
Solicitud
Solicitud HTTP
GET https://youtubeanalytics.googleapis.com/v2/reports
Se deben autorizar todas las solicitudes a la API de YouTube Analytics. En la guía de autorización, se explica cómo usar el protocolo de OAuth 2.0 para recuperar tokens de autorización.
Las solicitudes a la API de YouTube Analytics usan los siguientes permisos 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 métricas de rendimiento de los anuncios y de ingresos estimados. |
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 los grupos y los elementos de grupos de YouTube Analytics. |
https://www.googleapis.com/auth/youtubepartner | Ver y administrar los activos de YouTube y el contenido asociado en YouTube En la API de YouTube Analytics, los propietarios de contenido usan este alcance para administrar los grupos y los elementos de grupos de YouTube Analytics. |
Parámetros
En las siguientes tablas, se enumeran los parámetros de consulta obligatorios y opcionales para las solicitudes a la API que recuperan informes de consultas. Los parámetros de consulta estándar que se enumeran en la tabla también son opcionales y son compatibles con muchas APIs de Google.
Parámetros | ||
---|---|---|
Parámetros obligatorios | ||
endDate |
string Es 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 para el que todas las métricas de la consulta están disponibles en el momento de la consulta. Por ejemplo, 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 incluirán datos en la respuesta. (Esto es cierto 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 para el que recuperas datos de YouTube Analytics.
|
|
metrics |
string Es una lista separada por comas de métricas de YouTube Analytics, como views o likes,dislikes . Consulta la documentación de los informes de canales o los informes de propietarios del contenido para obtener una lista de los informes que puedes recuperar y las métricas disponibles en cada uno. (El documento Métricas contiene las definiciones de todas las métricas).
|
|
startDate |
string Fecha de inicio para recuperar 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 devuelve la API para esas métricas son estimaciones calculadas 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 de tres letras según la norma ISO 4217 de la siguiente lista de monedas. 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 dimensiones de YouTube Analytics, como video o ageGroup,gender . Consulta la documentación de los informes de canales o los informes de propietarios del contenido para obtener una lista de los informes que puedes recuperar y las dimensiones que se usan en ellos. (El documento Dimensiones contiene definiciones para todas las dimensiones).
|
|
filters |
string Es una lista de filtros que se deben aplicar cuando se recuperan datos de YouTube Analytics. En la documentación de los informes de canales y los informes de propietarios del contenido, se identifican las dimensiones que se pueden usar para filtrar cada informe, y el documento Dimensiones define esas dimensiones. Si una solicitud usa varios filtros, únelos con un punto y coma ( ; ), y la tabla de resultados que se muestre satisfará ambos filtros. Por ejemplo, un valor del parámetro filters de video==dMH0bHeiRNg;country==IT restringe el conjunto de resultados para que incluya datos del video determinado en Italia.Cómo especificar varios valores para un filtro La API admite la capacidad de especificar varios valores para los filtros video , playlist y channel . Para ello, especifica una lista separada de los IDs de los videos, las playlists o los 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 que incluya datos de los videos determinados en Italia. El valor del parámetro puede especificar hasta 500 IDs.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 es así 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 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 agrega estadísticas de vistas según la forma en que los usuarios llegaron al contenido de video del canal. Supongamos también que el parámetro filters de tu solicitud identifica una lista de 10 videos para los que se deben devolver datos.
|
|
includeHistoricalChannelData |
boolean Nota: Este parámetro solo se aplica a los informes de propietarios del contenido. Indica si la respuesta de la API debe incluir los datos de tiempo de reproducción y vistas de los canales del período anterior a la vinculación de los canales con el propietario del contenido. El valor predeterminado del parámetro es false , lo que significa que la respuesta de la API solo incluye datos de tiempo de reproducción y vistas de las fechas en que los canales se vincularon al propietario del contenido.Es importante recordar que es posible que diferentes canales se hayan vinculado a un propietario de contenido en fechas distintas. 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 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 llamaba include-historical-channel-data |
|
maxResults |
integer Es la cantidad máxima de filas que se incluirán en la respuesta. Nota: En la versión 1 de la API, este parámetro se llamaba max-results |
|
sort |
string Es una lista separada por comas de dimensiones o métricas que determinan el orden de clasificación de los datos de YouTube Analytics. El orden de clasificación predeterminado es ascendente El prefijo - provoca un orden de clasificación descendente.
|
|
startIndex |
integer Índice basado en 1 de la primera entidad que se recuperará. (El valor predeterminado es 1 ). Usa este parámetro como 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 de OAuth 2.0 para el usuario actual.
|
|
alt |
Este parámetro no se admite en la versión 2 de la API, que solo admite respuestas en formato JSON. Es el formato de datos para la respuesta de la API.
|
|
callback |
Función de devolución de llamada
|
|
prettyPrint |
Muestra una respuesta con sangrías y saltos de línea.
|
|
quotaUser |
Este parámetro se admitía en la versión 1 de la API, que ahora dejó de estar disponible. Este parámetro no se admite en la versión 2 de la API. | |
userIp |
Este parámetro se admitía en la versión 1 de la API, que ahora dejó de estar disponible. Este parámetro no se admite en 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 indica en la definición del parámetro alt
, la API puede devolver respuestas en formato JSON o CSV. La información sobre el cuerpo de la respuesta para cada tipo se muestra a continuación:
{ "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 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 delimitados por comas.La lista columnHeaders comienza con las dimensiones especificadas en la solicitud de la API, seguidas de las métricas especificadas en la solicitud de la API. El orden de las dimensiones y las métricas coincide con el orden de la solicitud de API.Por ejemplo, si la solicitud de API contiene los parámetros dimensions=ageGroup,gender&metrics=viewerPercentage , la respuesta de la API devuelve columnas en este orden: ageGroup ,gender ,viewerPercentage . |
columnHeaders[].name |
string Es el nombre de la dimensión o la métrica. |
columnHeaders[].columnType |
string Es el tipo de la columna ( DIMENSION o METRIC ). |
columnHeaders[].dataType |
string Es el tipo de datos de la columna ( STRING , INTEGER , FLOAT , etcétera). |
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 se indican 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 búsqueda con la dimensión day no contendrá filas para los días más recientes. |
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 las bibliotecas cliente para obtener una lista de los idiomas 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 que autoriza la llamada para el año calendario 2017. En la muestra, se usa la biblioteca cliente de JavaScript de las APIs de Google.Antes de ejecutar esta muestra de forma local por primera vez, debes configurar las credenciales de autorización para tu proyecto:
- Crea o selecciona un proyecto en la Consola de APIs de Google.
- Habilita la API de YouTube Analytics para tu proyecto.
- 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 se configuró y haz clic en el botón Guardar.
- En la página Credenciales, haz clic en el botón Crear credenciales y selecciona ID de cliente de OAuth.
- Selecciona el tipo de aplicación Aplicación web.
- En el campo Orígenes autorizados de JavaScript, ingresa la URL desde la que entregarás el código de muestra. Por ejemplo, podrías usar algo como
http://localhost:8000
ohttp://yourserver.example.com
. Puedes dejar en blanco el campo URIs de redireccionamiento autorizados. - Haz clic en el botón Crear para terminar de crear tus credenciales.
- 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:
- Abre el archivo local desde un navegador web y abre la consola de depuración en el navegador. Deberías ver una página con dos botones.
- Haz clic en el botón Autorizar y cargar para iniciar el flujo de autorización del usuario. Si autorizas a la app para que recupere los datos de tu canal, deberías ver las siguientes líneas impresas en la consola del navegador:
Sign-in successful GAPI client loaded for API
- 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.
- Haz clic en el botón Ejecutar para llamar a la API. Deberías ver un objeto
response
impreso en la consola del navegador. En ese objeto, la propiedadresult
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 las vistas diarias y otras métricas del canal del usuario que autoriza la llamada para el año calendario 2017. En la muestra, se usa la biblioteca cliente de las APIs de Google para Python.Antes de ejecutar esta muestra de forma local por primera vez, debes configurar las credenciales de autorización para tu proyecto:
- Crea o selecciona un proyecto en la Consola de APIs de Google.
- Habilita la API de YouTube Analytics para tu proyecto.
- 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 se configuró y haz clic en el botón Guardar.
- En la página Credenciales, haz clic en el botón Crear credenciales y selecciona ID de cliente de OAuth.
- Selecciona el tipo de aplicación Otro, ingresa el nombre "Guía de inicio rápido de la API de YouTube Analytics" y haz clic en el botón Crear.
- Haz clic en Aceptar para descartar el diálogo resultante.
- Haz clic en el botón (Descargar JSON) a la derecha del ID de cliente.
- Mueve el archivo descargado a tu directorio de trabajo.
También debes 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:
- Copia el siguiente código de muestra en tu directorio de trabajo.
- 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. - Ejecuta el código de muestra en una ventana de terminal:
python yt_analytics_v2.py
- Completa el flujo de autorización. Es posible que el flujo de autorización se cargue automáticamente en tu navegador, o que debas copiar la URL de autorización en una ventana del navegador. Al final del flujo de autorización, si es necesario, pega el código de autorización que se muestra en el navegador en la ventana de la terminal y haz clic en [return].
- Se ejecuta la consulta de la API y la respuesta JSON se muestra en 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ébalo
Usa APIs Explorer para llamar a esta API y ver la solicitud y la respuesta de la API.