Questa pagina è stata tradotta dall'API Cloud Translation.

YouTube Analytics API - Data Model

L'API di YouTube Analytics ti consente di generare report personalizzati contenenti i dati di YouTube Analytics. L'API supporta i report per i canali e per i proprietari dei contenuti. I campi dei report sono caratterizzati da dimensioni o metriche:

Le dimensioni sono criteri comuni utilizzati per aggregare i dati, ad esempio la data in cui si è verificata un'azione o il paese in cui si trovano gli utenti.

In un report, ogni riga di dati ha una combinazione unica di valori di dimensioni. Pertanto, le dimensioni scelte per un report determinano il modo in cui YouTube calcola i valori per le metriche in quel report.
Le metriche sono misurazioni individuali relative all'attività utente, al rendimento degli annunci o alle entrate stimate. Le metriche relative alle attività degli utenti includono, ad esempio, il numero di visualizzazioni e di valutazioni (Mi piace e Non mi piace).

L'API di Analytics fornisce parametri di filtro e ordinamento, pertanto l'applicazione di chiamata non deve supportare in modo nativo tali funzioni. L'API ti consente inoltre di recuperare i dati per i gruppi di YouTube Analytics, in cui un gruppo è una raccolta personalizzata di massimo 500 video, playlist, canali o asset.

Scelta dei parametri dei report

Quando richiedi un report, utilizzando il metodo reports.query dell'API, la richiesta API contiene cinque parametri che determinano la modalità di calcolo dei valori del report:

I parametri startDate e endDate specificano il periodo di tempo durante il quale il report conterrà dati. La risposta API in realtà contiene dati che risalgono all'ultimo giorno specificato per cui tutte le metriche nella query sono disponibili al momento della query.
Il parametro metrics specifica le misurazioni che verranno incluse nel report. Nei report sui canali, le metriche misurano l'attività utente e includono valori come visualizzazioni e Mi piace. Alcune metriche misurano anche il rendimento degli annunci o le entrate stimate.
Il parametro dimensions spiega come verranno raggruppate le metriche.
Il parametro filters spiega in che modo verranno filtrati i dati del report. Quindi, ad esempio, invece di restituire tutti i dati di un canale, puoi filtrare un report in modo da contenere soltanto le metriche relative a un paese, un video o un gruppo di video specifico.

Nota: l'API consente di specificare più valori per i filtri video, playlist e canale. In tal caso, puoi anche includere il filtro nell'elenco delle dimensioni in modo che le metriche restituite siano raggruppate anche per video, playlist o canale.

Esempi di report disponibili

Ad esempio, supponiamo che il proprietario di un canale voglia recuperare un report sui tipi di dispositivi video per determinare il numero di visualizzazioni dei video del canale su dispositivi mobili, console per videogiochi, TV e così via.

Il proprietario del canale imposta il parametro startDate su 2015-06-01 e il parametro endDate su 2015-07-31. In base a questi valori, il report conterrà i dati per un periodo di due mesi.
Il report sul tipo di dispositivo supporta le metriche views e estimatedMinutesWatched, quindi il proprietario del canale imposta il parametro metrics su views,estimatedMinutesWatched.
Per il parametro dimensions, il proprietario del canale ha a disposizione una serie di opzioni. Due di queste regole sono mostrate nell'elenco che segue e una terza viene illustrata nella spiegazione del valore del parametro filters più avanti in questa sezione.
- Se imposti il valore parametro su deviceType, i conteggi delle visualizzazioni e del tempo di visualizzazione vengono raggruppati per tipo di dispositivo per l'intero periodo considerato dal report. Quindi, con questo valore, i dati del report risponderanno a domande come:
  - Quante volte i video del canale sono stati visualizzati sui dispositivi mobili tra il 1° giugno 2015 e il 31 luglio 2015?
  - Quante volte i video del canale sono stati visualizzati sulle console per videogiochi tra il 1° giugno 2015 e il 31 luglio 2015?
  Il report conterrà in realtà il totale delle visualizzazioni e del tempo di visualizzazione per ciascun tipo di dispositivo.
- Se imposti il valore parametro su day,deviceType, i conteggi delle visualizzazioni e del tempo di visualizzazione verranno calcolati per tipo di dispositivo per ogni giorno durante il periodo del report. Quindi, con questo valore, i dati del report risponderanno a domande come:
  - Quante volte i video del canale sono stati visualizzati sui dispositivi mobili il 1° giugno 2015?
  - Quante volte i video del canale sono stati visualizzati in televisione il 14 luglio 2015?
Infine, il parametro filters consente al proprietario del canale di limitare l'inclusione nel report solo dei dati corrispondenti a determinati valori del filtro. Il report supporta troppe opzioni di filtro per spiegarle tutte, pertanto questi esempi rappresentano solo una parte dei report che potresti generare.
- Il proprietario del canale potrebbe filtrare la richiesta di restituzione dei valori solo per il sistema operativo Android. Quante visualizzazioni si sono verificate sui dispositivi mobili Android durante il periodo del report?
- Il proprietario del canale potrebbe filtrare la richiesta di restituzione dei valori solo per un determinato paese. Quante volte sono stati visualizzati video in Canada ogni giorno del periodo del report?
- Il proprietario del canale potrebbe filtrare la richiesta di restituzione dei valori solo per determinati video. Tuttavia, il filtro video supporta un elenco di valori separato da virgole che potrebbe contenere dati per tanti video.
  
  Inoltre, se il filtro video specifica più valori, è possibile specificare anche video come dimensione. Ciò significa che il parametro dimensions supporta anche i valori deviceType,video e day,deviceType,video.
  - Se il proprietario del canale include video nell'elenco delle dimensioni, le metriche specificano i singoli valori per ogni video. Quante volte è stato visualizzato il video XYZ su una console per videogiochi il 1° giugno 2015?
  - Se il proprietario del canale non include il video nell'elenco delle dimensioni, le metriche specificano i valori totali che coprono tutti i video specificati. Quante volte sono stati visualizzati i video ABC, DEF e XYZ su una console per videogiochi il 1° giugno 2015?

Recupero di report

Per recuperare un report, invia una richiesta GET autorizzata al metodo reports.query dell'API, specificando i parametri che definiscono il report da recuperare.

Consulta la documentazione relativa ai report sui canali e ai report sui proprietari dei contenuti per un elenco dei report supportati dall'API. Ogni definizione di report identifica i valori consentiti dal report per i parametri metrics, dimensions e filters.

Best practice

Le applicazioni che utilizzano l'API di YouTube Analytics devono sempre seguire queste pratiche:

Utilizza la riga di intestazione di una risposta per determinare l'ordine delle colonne del report. Ad esempio, non dare per scontato che le visualizzazioni siano la prima metrica restituita in una risposta solo perché è la prima metrica elencata in una descrizione del report. Utilizza invece la riga di intestazione della risposta per determinare quale colonna contiene i dati.
Utilizza l'API di dati di YouTube per recuperare i metadati aggiuntivi per le risorse identificate nelle risposte dell'API di YouTube Analytics. Come indicato nelle Norme per gli sviluppatori di servizi API di YouTube (sezioni da III.E.4.b a III.E.4.d), i client API devono eliminare o aggiornare i metadati delle risorse archiviate da questa API dopo 30 giorni.

Metriche aggregate ed elementi eliminati

Le risposte dell'API di YouTube Analytics non contengono suddivisioni delle metriche per gli elementi eliminati. Ad esempio, se il proprietario di un canale elimina un video, questo non sarà più elencato in una risposta dell'API che restituisce metriche video per video. Tuttavia, i report che aggregano le metriche per un insieme di risorse includono ancora le metriche associate agli elementi eliminati.

Ad esempio, supponiamo che il proprietario di un canale recuperi due report. Il primo report elenca le visualizzazioni giornaliere totali di tutti i video del canale in un determinato periodo di tempo. Il secondo report elenca le visualizzazioni giornaliere totali video per video nello stesso periodo di tempo.

In questo caso, i numeri nel primo report includeranno le visualizzazioni dei video che sono stati eliminati in un secondo momento perché il primo report contiene aggregati giornalieri. Tuttavia, il secondo non includerà le visualizzazioni associate agli elementi eliminati perché il secondo elenca le visualizzazioni video per video. Di conseguenza, se il canale ha eliminato i video durante il periodo di tempo considerato dal report, il numero totale di visualizzazioni registrate nel primo report potrebbe essere maggiore della somma dei conteggi giornalieri specifici per i video nel secondo report.

Anonimizzazione dei dati

Alcuni dati di YouTube Analytics sono limitati quando le metriche non soddisfano una determinata soglia. Ciò può accadere in una varietà di report. In pratica, significa che un report potrebbe non contenere tutti i dati (o qualunque) se:

un video o un canale ha un traffico limitato durante un periodo di tempo specificato,

o
Hai selezionato un filtro o una dimensione, ad esempio la sorgente di traffico o il paese, per i quali non viene raggiunta una determinata soglia.

Nei casi in cui i dati sono limitati, potrebbe esserci una differenza tra i totali riportati nei vari report, a seconda di come questi ultimi aggregano i dati.

Ad esempio, supponiamo che il proprietario di un canale recuperi due report. Il primo report elenca le visualizzazioni totali di un determinato video, mentre il secondo indica le visualizzazioni totali di quel video in base al paese. Durante il periodo di tempo specificato, supponiamo che il video sia stato visualizzato 1000 volte, mentre 500 visualizzazioni negli Stati Uniti, 498 in Canada e due in Francia.

In questo esempio, il primo report indica che il video è stato visualizzato 1000 volte. Il secondo report indicherebbe solo che il video è stato visualizzato 500 volte negli Stati Uniti e 498 volte in Canada. Pertanto, ci sarebbe una differenza tra i conteggi totali delle visualizzazioni nei due report. Tieni presente che il secondo report non contiene alcuna indicazione sul fatto che siano avvenute altre due viste (oppure che le visualizzazioni si sono verificate in Francia).

Le soglie effettive in cui i dati sono limitati non vengono pubblicate e soggette a modifiche a discrezione di YouTube.

Tipi di dati limitati

I seguenti dati potrebbero essere limitati nei report di YouTube Analytics:

Dati demografici, come età e genere.
Dati geografici, incluse metriche o dimensioni relative ai paesi o alle aree geografiche in cui si trovano gli spettatori, ad esempio paesi o aree geografiche. Tieni presente, tuttavia, che i report non applicano le soglie geografiche alle metriche relative alle entrate.
Metriche correlate a sorgenti di traffico specifiche, ad esempio termini di ricerca o URL esterni che hanno generato visualizzazioni dei tuoi video. Ad esempio, i termini di ricerca e gli URL che generano un numero molto ridotto di visualizzazioni non appariranno nei report, anche se continuerai a vedere termini e URL che indirizzano molti spettatori verso i tuoi contenuti.

Consulta il Centro assistenza YouTube per scoprire di più sui dati soggetti a limiti nei report di YouTube Analytics.

Utilizzo quota

Ogni richiesta API effettuata viene conteggiata come un'unità della quota di utilizzo dell'API. I limiti di quota sono visibili nel riquadro Quote nella console API di Google.