YouTube Analytics API - Data Model

L'API di YouTube Analytics 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 come 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 trovavano gli utenti.

  In un report, ogni riga di dati ha una combinazione unica di valori delle dimensioni. Pertanto, le dimensioni che scegli per un report determinano il modo in cui YouTube calcola i valori delle metriche nel report.

• Le metriche sono misurazioni individuali correlate all'attività degli utenti, al rendimento degli annunci o alle entrate stimate. Le metriche sull'attività degli utenti includono elementi come il numero di visualizzazioni e le valutazioni (Mi piace e Non mi piace) dei video.

L'API Analytics fornisce parametri di filtro e ordinamento, pertanto l'applicazione chiamante non deve supportare nativamente queste funzioni. L'API consente anche di recuperare i dati per i gruppi di YouTube Analytics, dove un gruppo è una raccolta personalizzata di massimo 500 video, playlist, canali o risorse.

Scegliere i parametri del report

Quando richiedi un report utilizzando il metodo reports.query dell'API, la richiesta API contiene cinque parametri che determinano il modo in cui verranno calcolati i valori del report:

• I parametri startDate e endDate specificano il periodo di tempo per il quale il report conterrà i dati. La risposta dell'API contiene dati fino all'ultimo giorno specificato per il quale 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à degli utenti 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 come verranno filtrati i dati del report. Ad esempio, anziché restituire tutti i dati di un canale, un report potrebbe essere filtrato in modo da contenere solo le metriche relative a un determinato paese, video o gruppo di video.

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

Opzioni di reporting di esempio

Ad esempio, supponiamo che il proprietario di un canale voglia recuperare un report sul tipo di dispositivo video per determinare quante visualizzazioni dei video del canale si sono verificate 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 relativi a un periodo di due mesi.

• Il report sul tipo di dispositivo supporta le metriche visualizzazioni e estimatedMinutesWatched, pertanto il proprietario del canale imposta il parametro metrics su views,estimatedMinutesWatched.

• Per il parametro dimensions, il proprietario del canale ha diverse opzioni. Due di questi sono mostrati nel seguente elenco, mentre un terzo viene trattato nella spiegazione del valore del parametro filters più avanti in questa sezione.

  • Se imposti il valore del parametro su deviceType, i conteggi delle visualizzazioni e del tempo di visualizzazione verranno raggruppati per tipo di dispositivo per l'intero periodo coperto dal report. Pertanto, con questo valore, i dati del report risponderanno a domande come:

    • Quante volte sono stati visualizzati i video del canale sui dispositivi mobili tra il 1° giugno 2015 e il 31 luglio 2015?
    • Quante volte sono stati visualizzati i video del canale sulle console per videogiochi tra il 1° giugno 2015 e il 31 luglio 2015?

    Il report conterrà un conteggio totale di visualizzazioni e tempo di visualizzazione per ogni tipo di dispositivo.

  • Se imposti il valore del parametro su day,deviceType, i conteggi delle visualizzazioni e del tempo di visualizzazione verranno calcolati in base al tipo di dispositivo per ogni giorno del periodo del report. Pertanto, con questo valore, i dati del report risponderanno a domande come:

    • Quante volte sono stati visualizzati i video del canale sui dispositivi mobili il 1° giugno 2015?
    • Quante volte sono stati visualizzati i video del canale sulle televisioni il 14 luglio 2015?

• Infine, il parametro filters consente al proprietario del canale di limitare il report in modo che includa solo i dati corrispondenti a determinati valori di filtro. Il report supporta troppe opzioni di filtraggio per poterle spiegare tutte, quindi questi esempi rappresentano solo una frazione dei report che potresti generare.

  • Il proprietario del canale potrebbe filtrare la richiesta per restituire 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 in modo da restituire valori solo per un determinato paese. (Quante volte sono stati visualizzati i video in Canada in ogni giorno del periodo del report?)

  • Il proprietario del canale potrebbe filtrare la richiesta in modo da restituire valori solo per video particolari. Tuttavia, il filtro Video supporta un elenco di valori separati da virgola, quindi il report potrebbe contenere dati per molti video.

    Inoltre, se il filtro video specifica più valori, è possibile specificare video anche 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 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 dei 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 sui report sui canali e sui report sui proprietari dei contenuti per un elenco dei report supportati dall'API. Ogni definizione del report identifica i valori consentiti dal report per i parametri metrics, dimensions e filters.

Best practice

Le applicazioni che utilizzano l'API 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 saranno la prima metrica restituita in una risposta solo perché è la prima metrica elencata nella descrizione di un report. Utilizza invece la riga di intestazione della risposta per determinare la colonna contenente i dati.
• Utilizza l'API YouTube Data per recuperare metadati aggiuntivi per le risorse identificate nelle risposte dell'API YouTube Analytics. Come indicato nelle Norme per gli sviluppatori dei 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 archiviati da quell'API dopo 30 giorni.

Metriche aggregate ed elementi eliminati

Le risposte dell'API YouTube Analytics non contengono suddivisioni delle metriche per gli elementi eliminati. Ad esempio, se il proprietario di un canale elimina un video, questo non verrà più elencato in una risposta 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 del primo report includeranno le visualizzazioni dei video che sono stati eliminati in un secondo momento perché il primo report contiene aggregazioni giornaliere. Tuttavia, il secondo report non includerà le visualizzazioni associate agli elementi eliminati perché elenca le visualizzazioni video per video. Di conseguenza, se il canale ha eliminato video durante il periodo di tempo coperto dal report, il numero totale di visualizzazioni giornaliere riportato nel primo report potrebbe essere superiore alla somma delle visualizzazioni giornaliere specifiche per video nel secondo report.

Anonimizzazione dei dati

Alcuni dati di YouTube Analytics sono limitati quando le metriche non raggiungono determinate soglie. Ciò può accadere in diversi report. In pratica, un report potrebbe non contenere tutti i tuoi dati (o nessuno) se:

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

   o

2. hai selezionato un filtro o una dimensione, ad esempio l'origine del traffico o il paese, i cui valori non raggiungono una determinata soglia.

In caso di dati limitati, potrebbe esserci una differenza tra i totali riportati in diversi 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 elenca le visualizzazioni totali dello stesso video in base al paese. Durante il periodo di tempo specificato, supponiamo che il video abbia ottenuto 1000 visualizzazioni, di cui 500 negli Stati Uniti, 498 in Canada e 2 in Francia.

In questo esempio, il primo report indicherebbe 1000 visualizzazioni. Il secondo report indicherebbe solo che il video è stato visualizzato 500 volte negli Stati Uniti e 498 volte in Canada. Di conseguenza, si verifica una differenza tra il numero totale delle visualizzazioni nei due report. Tieni presente che il secondo report non conterrà alcuna indicazione che si sono verificate anche altre due visualizzazioni (o che si sono verificate visualizzazioni in Francia).

Le soglie effettive al di sotto delle quali i dati sono limitati non vengono pubblicate e sono soggette a modifiche a discrezione di YouTube.

Tipi di dati limitati

I seguenti dati potrebbero essere soggetti a limiti nei report di YouTube Analytics:

• Dati demografici, come età e genere.
• Dati geografici, incluse metriche o dimensioni relative ai paesi o alle regioni in cui si trovavano gli spettatori, ad esempio i loro paesi o regioni. Tieni presente, tuttavia, che i report non applicano soglie geografiche alle metriche sulle entrate.
• Metriche relative a sorgenti di traffico specifiche, come 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 verranno visualizzati nei report, mentre continuerai a vedere i termini e gli URL che indirizzano molti spettatori ai tuoi contenuti.

Per ulteriori informazioni sui dati soggetti a limiti nei report di YouTube Analytics, consulta il Centro assistenza YouTube.

Utilizzo della quota

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