YouTube Analytics API - Data Model

L'API YouTube Analytics consente di generare report personalizzati contenenti dati di YouTube Analytics. L'API supporta i report per i canali e per i proprietari dei contenuti. I campi dei report sono classificati 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 di dimensione. Pertanto, le dimensioni scelte per un report determinano il modo in cui YouTube calcola i valori delle metriche in quel report.

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

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

Scegliere i parametri dei 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 effettivamente i 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à 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 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 per un determinato paese, video o gruppo di video.

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

Esempi di opzioni di reporting

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 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 diverse opzioni. Due di queste sono mostrate nell'elenco seguente e una terza è descritta nella spiegazione del valore 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. Con questo valore, i dati del report risponderanno a domande come:

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

    Il report conterrà effettivamente un conteggio totale delle visualizzazioni e del tempo di visualizzazione per ogni 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. Con questo valore, i dati del report risponderanno a domande come:

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

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

  • Il proprietario del canale potrebbe filtrare la richiesta in modo da restituire i valori solo per il sistema operativo Android. Quante visualizzazioni si sono verificate su dispositivi mobili Android durante il periodo del report?

  • Il proprietario del canale potrebbe filtrare la richiesta in modo da restituire i 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 i valori solo per determinati video. Tuttavia, il filtro video supporta un elenco separato da virgole, quindi il report potrebbe effettivamente contenere dati per molti video.

    Inoltre, se il filtro video specifica più valori, video può essere specificato anche come dimensione. Ciò significa che il dimensions parametro 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 valori individuali 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 riguardano tutti i video specificati. (Quante volte sono stati visualizzati i video ABC, DEF e XYZ su una console per videogiochi il 1° giugno 2015?)

Aggiornamento e latenza dei dati

Sebbene l'API di YouTube Analytics supporti le query mirate, i dati di analisi sottostanti non sono in tempo reale. L'elaborazione dei dati introduce in genere una latenza di 48-72 ore. Pertanto, le risposte dell'API non contengono dati per i giorni più recenti e il parametro endDate del report include solo i dati fino all'ultimo giorno per il quale tutte le metriche richieste sono completamente elaborate.

A causa della latenza dei dati, potresti notare discrepanze tra i dati restituiti dall'API e le metriche in tempo reale visibili in YouTube Studio. Se la tua applicazione richiede statistiche in tempo reale per i singoli video, ad esempio i conteggi correnti di visualizzazioni, Mi piace o commenti, utilizza il metodo videos.list dell'API YouTube Data anziché l'API di YouTube Analytics.

Recuperare i report

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

Consulta la documentazione sui report sui canali e sui report dei 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 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 di YouTube Analytics. Come indicato nelle Norme per gli sviluppatori dei servizi API di YouTube (sezioni III.E.4.b-III.E.4.d), i client API devono eliminare o aggiornare i metadati delle risorse memorizzati 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 verrà più elencato in una risposta dell'API che restituisce le metriche video per video. Tuttavia, i report che aggregano le metriche per un insieme di risorse includono ancora le metriche associate agli elementi eliminati.

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 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 i video durante il periodo di tempo coperto dal report, i conteggi totali delle visualizzazioni giornaliere riportati nel primo report potrebbero essere superiori alla somma dei conteggi delle visualizzazioni giornaliere specifiche per i video nel secondo report.

Anonimizzazione dei dati

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

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

   o

2. hai selezionato un filtro o una dimensione, ad esempio sorgente di traffico o 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.

Supponiamo che il proprietario di un canale recuperi due report. Il primo report elenca le visualizzazioni totali di un determinato video, mentre il secondo report elenca le visualizzazioni totali di quel video paese per 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 che il video ha ottenuto 1000 visualizzazioni. Il secondo report indicherebbe solo che il video ha ottenuto 500 visualizzazioni negli Stati Uniti e 498 in Canada. Pertanto, ci sarebbe una differenza tra i conteggi totali delle visualizzazioni nei due report. Tieni presente che il secondo report non conterrebbe alcuna indicazione che si sono verificate 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 limitati nei report di YouTube Analytics:

• Dati demografici, ad esempio 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 delle entrate.
• Metriche relative 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 verranno visualizzati nei report, anche se continuerai a vedere i termini e gli URL che indirizzano molti spettatori ai tuoi contenuti.

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

Utilizzo 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 nella console API di Google.