Reports: Query

Importante:le richieste API a questo metodo ora richiedono l'accesso all'ambito https://www.googleapis.com/auth/youtube.readonly.

Questo metodo ti consente di recuperare molti report Analytics diversi. Ogni richiesta utilizza parametri di query per specificare un ID canale o un proprietario dei contenuti, una data di inizio, una data di fine e almeno una metrica. Puoi anche fornire parametri di query aggiuntivi, come dimensioni, filtri e istruzioni di ordinamento.

  • Le metriche sono misurazioni individuali dell'attività degli utenti, come le visualizzazioni o le valutazioni (Mi piace e Non mi piace) dei video.
  • Le dimensioni sono criteri comuni utilizzati per aggregare i dati, ad esempio la data in cui si è verificata l'attività utente o il paese in cui si trovavano gli utenti. In un report, ogni riga di dati ha una combinazione unica di valori delle dimensioni.
  • I filtri sono valori di dimensione che specificano i dati da recuperare. Ad esempio, puoi recuperare i dati per un paese specifico, un video specifico o un gruppo di video.

Nota:i report dei proprietari dei contenuti sono accessibili solo ai partner di contenuti di YouTube che partecipano al Programma partner di YouTube.

Casi d'uso comuni

Richiesta

Richiesta HTTP

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

Tutte le richieste all'API YouTube Analytics devono essere autorizzate. La guida all'autorizzazione spiega come utilizzare il protocollo OAuth 2.0 per recuperare i token di autorizzazione.

Le richieste all'API YouTube Analytics utilizzano i seguenti ambiti di autorizzazione:

Ambiti
https://www.googleapis.com/auth/yt-analytics.readonly Visualizzare i report di YouTube Analytics per i contenuti di YouTube. Questo ambito fornisce l'accesso alle metriche sull'attività degli utenti, come i conteggi delle visualizzazioni e delle valutazioni.
https://www.googleapis.com/auth/yt-analytics-monetary.readonly Visualizzare i report Analytics su YouTube relativi al valore monetario per i contenuti di YouTube. Questo ambito fornisce l'accesso alle metriche sull'attività utente e alle metriche stimate su entrate e rendimento degli annunci.
https://www.googleapis.com/auth/youtube Gestire il tuo account YouTube. Nell'API YouTube Analytics, i proprietari dei canali utilizzano questo ambito per gestire i gruppi e gli elementi dei gruppi di YouTube Analytics.
https://www.googleapis.com/auth/youtubepartner Visualizzare e gestire le risorse di YouTube e i relativi contenuti su YouTube. Nell'API YouTube Analytics, i proprietari dei contenuti utilizzano questo ambito per gestire i gruppi e gli elementi dei gruppi di YouTube Analytics.

Parametri

Le tabelle seguenti elencano i parametri di query obbligatori e facoltativi per le richieste API per recuperare i report sulle query. Anche i parametri di query standard elencati nella tabella sono facoltativi e sono supportati da molte API di Google.

Parametri
Parametri obbligatori
endDate string
La data di fine per il recupero dei dati YouTube Analytics. Il valore deve essere nel formato YYYY-MM-DD.

La risposta dell'API contiene dati fino all'ultimo giorno per il quale tutte le metriche nella query sono disponibili al momento della query. Ad esempio, se la richiesta specifica una data di fine del 5 luglio 2017 e i valori per tutte le metriche richieste sono disponibili solo fino al 3 luglio 2017, questa sarà l'ultima data per cui i dati sono inclusi nella risposta. Ciò vale anche se i dati per alcune delle metriche richieste sono disponibili per il 4 luglio 2017.
Nota:nella versione 1 dell'API, questo parametro era denominato end-date.
ids string
Identifica il canale YouTube o il proprietario dei contenuti per cui stai recuperando i dati YouTube Analytics.

  • Per richiedere i dati di un canale YouTube, imposta il valore del parametro ids su channel==MINE o channel==CHANNEL_ID, dove CHANNEL_ID identifica il canale YouTube dell'utente attualmente autenticato.
  • Per richiedere i dati di un proprietario dei contenuti di YouTube, imposta il valore del parametro ids su contentOwner==OWNER_NAME, dove OWNER_NAME è l'content owner ID dell'utente.

metrics string
Un elenco separato da virgole di metriche YouTube Analytics, ad esempio views o likes,dislikes. Consulta la documentazione relativa ai report sui canali o ai report sui proprietari dei contenuti per un elenco dei report che puoi recuperare e delle metriche disponibili in ciascun report. Il documento Metriche contiene le definizioni di tutte le metriche.
startDate string
La data di inizio per il recupero dei dati YouTube Analytics. Il valore deve essere nel formato YYYY-MM-DD.
Nota:nella versione 1 dell'API, questo parametro era denominato start-date.
Parametri facoltativi
currency string
La valuta che l'API utilizzerà per specificare le seguenti metriche delle entrate stimate: estimatedRevenue, estimatedAdRevenue, estimatedRedPartnerRevenue, grossRevenue, cpm, playbackBasedCpm. I valori restituiti dall'API per queste metriche sono stime calcolate utilizzando tassi di cambio che cambiano quotidianamente. Se non viene richiesta nessuna di queste metriche, il parametro viene ignorato.

Il valore del parametro è un codice valuta ISO 4217 di tre lettere dell'elenco delle valute riportato di seguito. L'API restituisce un errore se viene specificata una valuta non supportata. Il valore predefinito è USD.

dimensions string
Un elenco separato da virgole delle dimensioni di YouTube Analytics, ad esempio video o ageGroup,gender. Consulta la documentazione relativa ai report sui canali o ai report sui proprietari dei contenuti per un elenco dei report che puoi recuperare e delle dimensioni utilizzate per questi report. Il documento Dimensioni contiene le definizioni di tutte le dimensioni.
filters string
Un elenco di filtri da applicare durante il recupero dei dati YouTube Analytics. La documentazione per i report sui canali e i report sui proprietari dei contenuti identifica le dimensioni che possono essere utilizzate per filtrare ogni report, mentre il documento Dimensioni definisce queste dimensioni.

Se una richiesta utilizza più filtri, uniscili con un punto e virgola (;) e la tabella dei risultati restituita soddisferà entrambi i filtri. Ad esempio, un valore del parametro filters pari a video==dMH0bHeiRNg;country==IT limita il set di risultati in modo da includere i dati per il video specificato in Italia.

Specifica di più valori per un filtro

L'API supporta la possibilità di specificare più valori per i filtri video, playlist e channel. A questo scopo, specifica un elenco separato degli ID di video, playlist o canali per cui la risposta dell'API deve essere filtrata. Ad esempio, un valore del parametro filters pari a video==pd1FJh59zxQ,Zhawgd0REhA;country==IT limita il set di risultati in modo da includere i dati per i video specificati in Italia. Il valore del parametro può specificare fino a 500 ID.

Quando specifichi più valori per lo stesso filtro, puoi anche aggiungere il filtro all'elenco delle dimensioni specificate per la richiesta. Questo vale anche se il filtro non è elencato come dimensione supportata per un determinato report. Se aggiungi il filtro all'elenco delle dimensioni, l'API utilizza anche i valori del filtro per raggruppare i risultati.

Ad esempio, supponiamo di recuperare il report sulle sorgenti di traffico di un canale, che aggrega le statistiche di visualizzazione in base al modo in cui gli spettatori hanno raggiunto i contenuti video del canale. Supponiamo inoltre che il parametro filters della richiesta identifichi un elenco di 10 video per i quali devono essere restituiti i dati.
  • Se aggiungi video al valore del parametro dimensions, la risposta dell'API fornirà statistiche separate sull'origine del traffico per ciascuno dei 10 video.
  • Se non aggiungi video al valore del parametro dimensions, la risposta dell'API aggregherà le statistiche sull'origine del traffico per tutti i 10 video.
includeHistoricalChannelData boolean
Nota:questo parametro si applica solo ai report del proprietario dei contenuti.

Indica se la risposta dell'API deve includere i dati relativi al tempo di visualizzazione e alle visualizzazioni dei canali nel periodo di tempo precedente al collegamento dei canali al proprietario dei contenuti. Il valore predefinito del parametro è false, il che significa che la risposta dell'API include solo i dati relativi al tempo di visualizzazione e alle visualizzazioni a partire dalle date in cui i canali sono stati collegati al proprietario dei contenuti.

È importante ricordare che canali diversi potrebbero essere stati collegati a un proprietario dei contenuti in date diverse. Se la richiesta API recupera dati per più canali e il valore del parametro è false, la risposta API contiene dati basati sulla data di collegamento per ogni canale. Se il valore del parametro è true, la risposta dell'API contiene i dati corrispondenti alle date specificate nella richiesta API.
Nota:nella versione 1 dell'API, questo parametro era denominato include-historical-channel-data.
maxResults integer
Il numero massimo di righe da includere nella risposta.
Nota:nella versione 1 dell'API, questo parametro era denominato max-results.
sort string
Un elenco separato da virgole di dimensioni o metriche che determinano l'ordinamento dei dati di YouTube Analytics. Per impostazione predefinita, l'ordine di ordinamento è crescente. Il prefisso - determina l'ordinamento decrescente.
startIndex integer
L'indice in base 1 della prima entità da recuperare. (Il valore predefinito è 1.) Utilizza questo parametro come meccanismo di paginazione insieme al parametro max-results.
Nota:nella versione 1 dell'API, questo parametro era denominato start-index.
Parametri standard
access_token Token OAuth 2.0 per l'utente corrente.
alt Questo parametro non è supportato nella versione 2 dell'API, che supporta solo le risposte JSON. Il formato dei dati per la risposta dell'API.
  • Valori validi: json, csv
  • Valore predefinito: json
callback Funzione di callback.
  • Nome della funzione di callback JavaScript che gestisce la risposta.
  • Utilizzato nelle richieste JavaScript JSON-P.
prettyPrint

Restituisce la risposta con rientri e interruzioni di riga.

  • Restituisce la risposta in un formato leggibile se true.
  • Valore predefinito: true.
  • Se questa opzione è false, può ridurre le dimensioni del payload di risposta, il che potrebbe portare a prestazioni migliori in alcuni ambienti.
quotaUser Questo parametro era supportato nella versione 1 dell'API, che ora è deprecata. Questo parametro non è supportato nella versione 2 dell'API.
userIp Questo parametro era supportato nella versione 1 dell'API, che ora è deprecata. Questo parametro non è supportato nella versione 2 dell'API.

Corpo della richiesta

Non inviare un corpo della richiesta quando chiami questo metodo.

Risposta

Come indicato nella definizione del parametro alt, l'API può restituire risposte in formato JSON o CSV. Di seguito sono riportate le informazioni sul corpo della risposta per ogni tipo:

JSON
{
  "kind": "youtubeAnalytics#resultTable",
  "columnHeaders": [
    {
      "name": string,
      "dataType": string,
      "columnType": string
    },
    ... more headers ...
  ],
  "rows": [
    [
      {value}, {value}, ...
    ]
  ]
}
Proprietà
kind string
Questo valore specifica il tipo di dati inclusi nella risposta dell'API. Per il metodo query, il valore della proprietà kind sarà youtubeAnalytics#resultTable. Tuttavia, se l'API aggiunge il supporto per altri metodi, le risposte API per questi metodi potrebbero introdurre altri valori della proprietà kind.
columnHeaders[] list
Questo valore specifica le informazioni sui dati restituiti nei campi rows. Ogni elemento dell'elenco columnHeaders identifica un campo restituito nel valore rows, che contiene un elenco di dati delimitati da virgole.

L'elenco columnHeaders inizia con le dimensioni specificate nella richiesta API, seguite dalle metriche specificate nella richiesta API. L'ordine delle dimensioni e delle metriche corrisponde all'ordine nella richiesta API.

Ad esempio, se la richiesta API contiene i parametri dimensions=ageGroup,gender&metrics=viewerPercentage, la risposta API restituisce le colonne in questo ordine: ageGroup,gender,viewerPercentage.
columnHeaders[].name string
Il nome della dimensione o della metrica.
columnHeaders[].columnType string
Il tipo di colonna (DIMENSION o METRIC).
columnHeaders[].dataType string
Il tipo di dati nella colonna (STRING, INTEGER, FLOAT e così via).
rows[] list
L'elenco contiene tutte le righe della tabella dei risultati. Ogni elemento dell'elenco è un array che contiene dati delimitati da virgole corrispondenti a una singola riga di dati. L'ordine dei campi di dati delimitati da virgole corrisponderà all'ordine delle colonne elencate nel campo columnHeaders.

Se non sono disponibili dati per la query specificata, l'elemento rows verrà omesso dalla risposta.

La risposta a una query con la dimensione day non conterrà righe per i giorni più recenti.

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

Esempi

Nota:i seguenti esempi di codice potrebbero non rappresentare tutti i linguaggi di programmazione supportati. Consulta la documentazione delle librerie client per un elenco delle lingue supportate.

JavaScript

Questo esempio chiama l'API YouTube Analytics per recuperare le visualizzazioni giornaliere e altre metriche per il canale dell'utente che autorizza per l'anno solare 2017. L'esempio utilizza la libreria client JavaScript delle API di Google.

Prima di eseguire questo esempio localmente per la prima volta, devi configurare le credenziali di autorizzazione per il tuo progetto:
  1. Crea o seleziona un progetto nella console API di Google.
  2. Attiva l'API YouTube Analytics per il tuo progetto.
  3. Nella parte superiore della pagina Credenziali, seleziona la scheda Schermata di consenso OAuth. Seleziona un indirizzo email, inserisci un nome prodotto se non è già impostato e fai clic sul pulsante Salva.
  4. Nella pagina Credenziali, fai clic sul pulsante Crea credenziali e seleziona ID client OAuth.
  5. Seleziona il tipo di applicazione Applicazione web.
  6. Nel campo Origini JavaScript autorizzate, inserisci l'URL da cui verrà pubblicato l'esempio di codice. Ad esempio, potresti utilizzare http://localhost:8000 o http://yourserver.example.com. Puoi lasciare vuoto il campo URI di reindirizzamento autorizzati.
  7. Fai clic sul pulsante Crea per completare la creazione delle credenziali.
  8. Prima di chiudere la finestra di dialogo, copia l'ID client, che dovrai inserire nell'esempio di codice.

Quindi, salva il campione in un file locale. Nell'esempio, trova la seguente riga e sostituisci YOUR_CLIENT_ID con l'ID client ottenuto durante la configurazione delle credenziali di autorizzazione.

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

Ora puoi testare il campione:

  1. Apri il file locale da un browser web e apri la console di debug nel browser. Dovresti visualizzare una pagina con due pulsanti.
  2. Fai clic sul pulsante Autorizza e carica per avviare il flusso di autorizzazione dell'utente. Se autorizzi l'app a recuperare i dati del tuo canale, nella console del browser dovresti visualizzare le seguenti righe:
    Sign-in successful
    GAPI client loaded for API
  3. Se visualizzi un messaggio di errore anziché le righe riportate sopra, verifica di caricare lo script dall'URI di reindirizzamento autorizzato che hai configurato per il tuo progetto e di aver inserito l'ID client nel codice come descritto sopra.
  4. Fai clic sul pulsante Esegui per chiamare l'API. Dovresti vedere un oggetto response stampato nella console del browser. In questo oggetto, la proprietà result viene mappata a un oggetto che contiene i dati dell'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

Questo esempio chiama l'API YouTube Analytics per recuperare le visualizzazioni giornaliere e altre metriche per il canale dell'utente che autorizza per l'anno solare 2017. L'esempio utilizza la libreria client Python delle API di Google.

Prima di eseguire questo esempio localmente per la prima volta, devi configurare le credenziali di autorizzazione per il tuo progetto:
  1. Crea o seleziona un progetto nella console API di Google.
  2. Attiva l'API YouTube Analytics per il tuo progetto.
  3. Nella parte superiore della pagina Credenziali, seleziona la scheda Schermata di consenso OAuth. Seleziona un indirizzo email, inserisci un nome prodotto se non è già impostato e fai clic sul pulsante Salva.
  4. Nella pagina Credenziali, fai clic sul pulsante Crea credenziali e seleziona ID client OAuth.
  5. Seleziona il tipo di applicazione Altro, inserisci il nome "Guida rapida API YouTube Analytics" e fai clic sul pulsante Crea.
  6. Fai clic su Ok per chiudere la finestra di dialogo risultante.
  7. Fai clic sul pulsante (Scarica JSON) a destra dell'ID client.
  8. Sposta il file scaricato nella directory di lavoro.

Devi anche installare la libreria client delle API di Google per Python e alcune librerie aggiuntive:

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

Ora puoi testare il campione:

  1. Copia il codice campione riportato di seguito nella tua directory di lavoro.
  2. Nell'esempio, aggiorna il valore della variabile CLIENT_SECRETS_FILE in modo che corrisponda alla posizione del file scaricato dopo aver configurato le credenziali di autorizzazione.
  3. Esegui il codice campione in una finestra del terminale:
    python yt_analytics_v2.py
  4. Segui il flusso di autorizzazione. Il flusso di autorizzazione potrebbe caricarsi automaticamente nel browser oppure potrebbe essere necessario copiare l'URL di autorizzazione in una finestra del browser. Al termine del flusso di autorizzazione, se necessario, incolla il codice di autorizzazione visualizzato nel browser nella finestra del terminale e fai clic su [Invio].
  5. La query API viene eseguita e la risposta JSON viene restituita nella finestra del terminale.
# -*- 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'
  )

Prova

Utilizza APIs Explorer per chiamare questa API e visualizzare la richiesta e la risposta dell'API.