Reports: Query

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

Questo metodo consente di recuperare molti report di Analytics diversi. Ogni richiesta utilizza i 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 ricerca aggiuntivi, come dimensioni, filtri e istruzioni di ordinamento.

  • Le metriche sono singole misurazioni dell'attività utente, ad esempio le visualizzazioni di video o le valutazioni (Mi piace e Non mi piace).
  • 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 univoca di valori delle dimensioni.
  • I filtri sono valori delle dimensioni che specificano i dati che verranno recuperati. Ad esempio, puoi recuperare i dati relativi a un paese specifico, a un video specifico o a un gruppo di video.

Nota: i report sui proprietari dei contenuti sono accessibili solo ai partner per i 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 API di 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 API di 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 tuoi contenuti di YouTube. Questo ambito fornisce l'accesso alle metriche relative all'attività degli utenti, come il numero di visualizzazioni e di valutazioni.
https://www.googleapis.com/auth/yt-analytics-monetary.readonly Visualizzare i report di YouTube Analytics relativi al valore monetario per i tuoi contenuti di YouTube. Questo ambito consente di accedere alle metriche dell'attività utente e alle metriche stimate relative al rendimento degli annunci e alle entrate.
https://www.googleapis.com/auth/youtube Gestisci 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 contenuti associati 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 seguenti tabelle 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 di YouTube Analytics. Il valore deve essere nel formato YYYY-MM-DD.

La risposta dell'API contiene dati fino all'ultimo giorno per cui sono disponibili tutte le metriche nella query al momento della query. Ad esempio, se la richiesta specifica la data di fine 5 luglio 2017 e i valori di tutte le metriche richieste sono disponibili solo fino al 3 luglio 2017, questa sarà l'ultima data per la quale i dati sono inclusi nella risposta. Ciò vale anche se i dati di 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 di YouTube Analytics.

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

metrics string
Un elenco separato da virgole di metriche YouTube Analytics, come 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 le 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 relative alle entrate stimate: estimatedRevenue, estimatedAdRevenue, estimatedRedPartnerRevenue, grossRevenue, cpm, playbackBasedCpm. I valori restituiti dall'API per queste metriche sono stime calcolati utilizzando tassi di cambio che cambiano su base giornaliera. Se non viene richiesta nessuna di queste metriche, il parametro viene ignorato.

Il valore del parametro è un codice valuta ISO 4217 a 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 di dimensioni di YouTube Analytics, come 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 le 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 di 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 e il documento Dimensioni le definisce.

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 l'insieme di risultati a includere dati per il video in questione 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 tale scopo, specifica un elenco separato contenente gli ID 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 l'insieme di risultati a includere i dati relativi ai video indicati in Italia. Il valore del parametro può specificare fino a 500 ID.

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

Ad esempio, supponi 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 anche che la richiesta relativa al parametro filters della tua 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 sulla sorgente di traffico per ciascuno dei dieci video.
  • Se non aggiungi video al valore del parametro dimensions, la risposta dell'API aggregherà le statistiche sulle sorgenti di traffico per tutti i 10 video.
includeHistoricalChannelData boolean
Nota:questo parametro si applica solo ai report dei proprietari dei contenuti.

Indica se la risposta dell'API deve includere i dati sulle visualizzazioni e sul tempo di visualizzazione dei canali relativi al periodo di tempo precedente a quello in cui i canali erano collegati 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 relativi alle date in cui i canali sono stati collegati al proprietario dei contenuti.

È importante ricordare che diversi canali 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 di ogni rispettivo canale. Se il valore del parametro è true, la risposta dell'API contiene 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'ordinamento è crescente. Il prefisso - determina un ordinamento decrescente.
startIndex integer
L'indice in base 1 della prima entità da recuperare. Il valore predefinito è 1. Utilizza questo parametro come meccanismo di impaginazione 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 JSON-P JavaScript.
prettyPrint

Restituisce la risposta con rientri e interruzioni di riga.

  • Restituisce la risposta in un formato leggibile se true.
  • Valore predefinito: true.
  • Quando questo valore è 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 il corpo di una 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 informazioni sul corpo della risposta per ciascun 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 dell'API per questi metodi potrebbero introdurre altri valori delle 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 dell'API restituisce le colonne in questo ordine: ageGroup,gender,viewerPercentage.
columnHeaders[].name string
Il nome della dimensione o 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 contenente dati separati da virgole corrispondenti a una singola riga di dati. L'ordine dei campi di dati separati da virgole corrisponderà all'ordine delle colonne elencate nel campo columnHeaders.

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

La risposta per una query con la dimensione day non conterrà righe relative ai 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 relativa alle librerie client per l'elenco dei linguaggi supportati.

JavaScript

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

Prima di eseguire questo esempio in locale per la prima volta, devi configurare le credenziali di autorizzazione per il 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 consenso OAuth. Seleziona un indirizzo email, inserisci il nome di un prodotto se non è già impostato e fai clic sul pulsante Salva.
  4. Nella pagina Credentials (Credenziali), fai clic sul pulsante Crea credenziali e seleziona ID client OAuth.
  5. Seleziona l'applicazione web del tipo di applicazione.
  6. Nel campo Origini JavaScript autorizzate, inserisci l'URL da cui verrà pubblicato l'esempio di codice. Ad esempio, puoi utilizzare qualcosa come 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 l'esempio in un file locale. Nell'esempio, individua la riga seguente 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 sei pronto per 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 di autorizzazione e caricamento per avviare il flusso di autorizzazione dell'utente. Se autorizzi l'app a recuperare i dati del tuo canale, nel browser dovrebbero essere visualizzate le seguenti righe per la console: 
    Sign-in successful
GAPI client loaded for API
  3. Se visualizzi un messaggio di errore al posto delle righe precedenti, verifica che stai caricando lo script dall'URI di reindirizzamento autorizzato che hai impostato per il tuo progetto e di aver inserito il tuo ID client nel codice come descritto sopra.
  4. Fai clic sul pulsante execute per chiamare l'API. Dovresti vedere un oggetto response stampato sulla console nel browser. In questo oggetto, la proprietà result viene mappata a un oggetto contenente 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>

yt_analytics_v2.html

Python

Questo esempio chiama l'API YouTube Analytics per recuperare le visualizzazioni giornaliere e altre metriche relative al canale dell'utente che ha autorizzato l'anno solare 2017. Nell'esempio viene utilizzata la libreria client Python delle API di Google.

Prima di eseguire questo esempio in locale per la prima volta, devi configurare le credenziali di autorizzazione per il 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 consenso OAuth. Seleziona un indirizzo email, inserisci il nome di un prodotto se non è già impostato e fai clic sul pulsante Salva.
  4. Nella pagina Credentials (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 di YouTube Analytics" e fai clic sul pulsante Crea.
  6. Fai clic su OK per chiudere la finestra di dialogo visualizzata.
  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 sei pronto per testare il campione:

  1. Copia l'esempio di codice 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 che hai scaricato dopo la configurazione delle 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 autenticazione potrebbe essere caricato automaticamente nel browser oppure potrebbe essere necessario copiare l'URL di autenticazione in una finestra del browser. Al termine del flusso di autorizzazione, se necessario, incolla nella finestra del terminale il codice di autorizzazione visualizzato nel browser e fai clic su [return].
  5. La query API viene eseguita e la risposta JSON viene inviata alla 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'
  )

yt_analytics_v2.py

Prova.

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