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 permette di recuperare molti report di Analytics diversi. Ogni richiesta utilizza parametri di ricerca 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 misurazioni individuali dell'attività degli utenti, ad esempio visualizzazioni o valutazioni dei video (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 trovano. In un report, ogni riga di dati ha una combinazione unica di valori di dimensioni.
  • I filtri sono valori di dimensione che specificano i dati che verranno recuperati. Ad esempio, puoi recuperare i dati relativi a un paese, a un video o a un gruppo di video specifici.

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

Casi d'uso comuni

Risorse richieste:

Richiesta HTTP

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

Tutte le richieste all'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 dell'API YouTube Analytics utilizzano i seguenti ambiti di autorizzazione:

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

Parametri

Le seguenti tabelle elencano i parametri di ricerca obbligatori e facoltativi per le richieste API per recuperare i report sulle query. Anche i parametri di ricerca standard elencati nella tabella sono facoltativi e 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 il quale tutte le metriche nella query sono disponibili al momento della query. Ad esempio, se la richiesta specifica una data di fine pari al 5 luglio 2017 e i valori di tutte le metriche richieste sono disponibili solo fino al 3 luglio 2017, questa sarà l'ultima data in cui i dati saranno inclusi nella risposta. anche se i dati di alcune metriche richieste sono disponibili per il 4 luglio 2017.
Nota: nella versione 1 dell'API, il parametro era denominato end-date.
ids string
Identifica il canale YouTube o il proprietario dei contenuti per il quale stai recuperando YouTube Analytics dati.

  • Per richiedere i dati per 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 per un proprietario di contenuti YouTube, imposta il valore del parametro ids su contentOwner==OWNER_NAME, dove OWNER_NAME è content owner ID per l'utente.

metrics string
Un elenco di YouTube Analytics metriche separate da virgole, ad esempio views o likes,dislikes. Consulta la documentazione per i report sui canali o i report sui proprietari dei contenuti per un elenco dei report che puoi recuperare e le metriche disponibili in ciascuno. Il documento Metrics contiene le definizioni di tutte le metriche.
startDate string
La data di inizio per il recupero dei dati di YouTube Analytics. Il valore deve essere nel formato YYYY-MM-DD.
Nota: nella versione 1 dell'API, il parametro era denominato start-date.
Parametri facoltativi
currency string
La valuta che verrà utilizzata dall'API per specificare le seguenti metriche relative alle entrate stimate: estimatedEntrate, estimatedAdEntrate, estimatedRedPartner Revenue, lordeEntrate, cpm, playbackBasedCpm. I valori restituiti dall'API per queste metriche sono stime calcolate utilizzando i tassi di cambio che cambiano ogni giorno. Se non viene richiesta alcuna di queste metriche, il parametro viene ignorato.

Il valore del parametro è un codice valuta ISO 4217 di tre lettere indicato nell'elenco delle valute di seguito. Se viene specificata una valuta non supportata, l'API restituisce un errore. Il valore predefinito è USD.

dimensions string
Un elenco di dimensioni di YouTube Analytics separate da virgole, come video o ageGroup,gender. Consulta la documentazione per i report sui canali o i 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 quando recuperi i 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 definisce tali 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 parametro filters di video==dMH0bHeiRNg;country==IT limita l'insieme di risultati in modo da includere i dati per il video in Italia.

Specificare più valori per un filtro

L'API supporta la possibilità di specificare più valori per i filtri video, playlist e channel. Per farlo, specifica un elenco separato di video, playlist o ID canale per i quali filtrare la risposta dell'API. Ad esempio, un valore parametro filters di video==pd1FJh59zxQ,Zhawgd0REhA;country==IT limita il set di risultati in modo da includere i dati per i video in Italia. Il valore parametro può specificare fino a 500 ID.

Quando specifichi più valori per lo stesso filtro, puoi anche aggiungerlo all'elenco delle dimensioni specificate per la richiesta. anche se il filtro non è elencato tra le dimensioni supportate per un determinato report. Se aggiungi il filtro all'elenco delle dimensioni, l'API utilizza i valori del filtro anche per raggruppare i risultati.

Ad esempio, supponiamo che tu recuperi 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. Inoltre, supponiamo che la richiesta del parametro filters della tua richiesta identifichi un elenco di 10 video per i quali restituire i dati.
  • Se aggiungi video al valore del parametro dimensions, la risposta dell'API fornirà statistiche separate sulla sorgente di traffico per ciascuno dei 10 video.
  • Se non aggiungi video al valore del parametro dimensions, la risposta dell'API aggrega le statistiche sulle sorgenti di traffico per tutti e 10 i video.
includeHistoricalChannelData boolean
Nota: questo parametro si applica solo ai report sul proprietario dei contenuti.

Indica se la risposta dell'API deve includere i dati relativi al tempo di visualizzazione e alle visualizzazioni dei canali relativi al periodo di tempo precedente al collegamento dei canali al proprietario dei contenuti. Il valore parametro predefinito è false, il che significa che la risposta API include solo i dati relativi al tempo di visualizzazione e alle visualizzazioni delle 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 sta recuperando dati per più canali e il valore parametro è false, la risposta dell'API conterrà i dati in base alla data di collegamento per ogni rispettivo 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, il parametro era denominato include-historical-channel-data.
maxResults integer
Il numero massimo di righe da includere nella risposta.
Nota: nella versione 1 dell'API, il parametro era denominato max-results.
sort string
Un elenco separato da virgole di dimensioni o metriche che determinano l'ordinamento per i dati di YouTube Analytics. Per impostazione predefinita, l'ordinamento è crescente. Il prefisso - causa 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 impaginazione insieme al parametro max-results.
Nota: nella versione 1 dell'API, il parametro era denominato start-index.
Parametri standard
access_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 di 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 questo valore è false, può ridurre le dimensioni del payload della risposta, il che potrebbe portare a prestazioni migliori in alcuni ambienti.
quotaUser Questo parametro era supportato nella versione 1 dell'API, che ora è obsoleta. Questo parametro non è supportato nella versione 2 dell'API.
userIp Questo parametro era supportato nella versione 1 dell'API, che ora è obsoleta. 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 le risposte in formato JSON o CSV. Di seguito sono riportate 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 di proprietà kind.
columnHeaders[] list
Questo valore specifica le informazioni sui dati restituiti nei campi rows. Ogni elemento nell'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 indicato 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 della 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 che corrispondono 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 viene omesso dalla risposta.

La risposta a una query con 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: gli esempi di codice riportati di seguito potrebbero non rappresentare tutti i linguaggi di programmazione supportati. Per un elenco delle lingue supportate, consulta la documentazione relativa alle librerie client.

JavaScript

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

Prima di eseguire questo esempio a livello 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. Attivare 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 Credenziali, fai clic sul pulsante Crea credenziali e seleziona ID client OAuth.
  5. Seleziona il tipo di applicazione Web.
  6. Nel campo Origini JavaScript autorizzate, inserisci l'URL da cui pubblicherà l'esempio di codice. Ad esempio, potresti 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 tutto è pronto per testare l'esempio:

  1. Apri il file locale da un browser web e apri la console di debug nel browser. Dovresti visualizzare una pagina che mostra 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, dovresti visualizzare le seguenti righe nella console nel browser:
    Sign-in successful
    GAPI client loaded for API
  3. Se vedi un messaggio di errore invece delle righe precedenti, verifica di caricare lo script dall'URI di reindirizzamento autorizzato che hai configurato per il tuo progetto e di inserire il tuo ID client nel codice, come descritto sopra.
  4. Fai clic sul pulsante execute per chiamare l'API. Dovresti vedere una stampa di oggetti response nella console nel browser. In tale 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>

Python

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

Prima di eseguire questo esempio a livello 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. Attivare 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 Credenziali, fai clic sul pulsante Crea credenziali e seleziona ID client OAuth.
  5. Seleziona il tipo di applicazione Altro, inserisci il nome "Guida rapida all'API di YouTube Analytics" e fai clic sul pulsante Crea.
  6. Fai clic su OK per ignorare 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 tutto è pronto per testare l'esempio:

  1. Copia l'esempio di codice seguente nella 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 la procedura di autorizzazione. Il flusso di autenticazione potrebbe essere caricato automaticamente nel browser oppure potresti dover copiare l'URL di autenticazione 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 generata 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.

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