Questa pagina elenca i report che i proprietari di canali possono recuperare con l'API YouTube Analytics. I report sul canale forniscono le metriche sull'attività utente relative a un canale specifico e misurano, ad esempio, le visualizzazioni dei video, le valutazioni e il numero di iscrizioni.
I report sui video forniscono statistiche su tutte le attività utente correlate ai video di un canale.
I report sulle playlist forniscono statistiche specificamente correlate alle visualizzazioni di video generate nel contesto di una playlist.
I report sul rendimento degli annunci contengono metriche relative alle entrate e al rendimento degli annunci. Utilizzano la dimensione adType per raggruppare le metriche in base ai tipi di annunci che sono stati pubblicati durante le riproduzioni video. La sezione dei report sul rendimento degli annunci illustra i due tipi di metriche di rendimento degli annunci supportati dall'API.
Recupero di una segnalazione
Per recuperare un report sui canali, devi impostare il valore del parametro ids nella richiesta API su uno dei seguenti valori:
channel==MINE - L'API restituisce i dati relativi al canale YouTube dell'utente autenticato.
channel==CHANNEL_ID – Imposta CHANNEL_ID sull'ID canale univoco del canale per il quale stai recuperando i dati. L'utente che autorizza la richiesta deve essere il proprietario del canale.
Attualmente l'ID canale è una stringa che inizia con le lettere UC, anche se il suo formato è soggetto a modifiche. Puoi trovare l'ID del canale nella pagina delle impostazioni avanzate dell'account del tuo canale YouTube oppure puoi recuperarlo in modo programmatico utilizzando il metodo channels.listYouTube Data API's.
Autorizzazione
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:
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.
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.
Nota: le metriche relative alle entrate stimate e al rendimento degli annunci non sono attualmente supportate per i report sui canali. Di conseguenza, l'ambito https://www.googleapis.com/auth/yt-analytics-monetary.readonly attualmente non concede l'accesso ai dati monetari in questi report.
Filtri
Le tabelle che illustrano i report supportati identificano i filtri che possono essere utilizzati per ciascun report. Nelle tabelle, i filtri mostrati tra parentesi sono facoltativi. Ad esempio, per l'opzione di filtro video(,country), il filtro video è obbligatorio, mentre il filtro paese è facoltativo.
L'API supporta anche la possibilità di specificare più valori per i filtri video e playlist. Se specifichi più valori per uno di questi filtri, puoi anche aggiungere il filtro all'elenco delle dimensioni specificate per la richiesta. Questo vale anche se il filtro non è elencato come dimensione supportata per un determinato report.
Consulta la definizione del parametro filters per una spiegazione completa su come filtrare i risultati dell'API per un valore o un insieme di valori specifico.
Informazioni sulle tabelle dei report
Questa sezione illustra la formattazione e la terminologia utilizzate nelle tabelle che definiscono i report supportati dall'API. Nella tabella seguente sono elencati le dimensioni, le metriche e i filtri supportati per il report video sui dettagli di riproduzione utilizzando la dimensione temporale e la metrica averageViewPercentage.
La tabella contiene due righe per le dimensioni, una per le metriche e tre per i filtri. Per le dimensioni e i filtri, i valori di ogni riga possono essere combinati in una richiesta API a condizione che la combinazione segua le regole di utilizzo riportate nella tabella. Ad esempio, i valori del parametro dimensions
validi per questo report includono:
dimensions=day
dimensions=day,liveOrOnDemand
dimensions=month,subscribedStatus,youtubeProduct
dimensions=month,youtubeProduct
Tuttavia, il valore del parametro day,month non è valido perché utilizza due dimensioni basate sul tempo, ma la richiesta può usare 0 o 1. In questo caso, il valore del parametro
subscribedStatus,youtubeProduct restituisce in realtà un report, ma le metriche non vengono
aggregate per giorno, settimana, mese e così via. Tale report è documentato separatamente nella documentazione.
Terminologia della tabella dei report
Le tabelle utilizzano la seguente terminologia per indicare se le dimensioni sono obbligatorie o facoltative:
a indicare che è necessario un valore:
Obbligatorio: devi includere il valore.
Utilizza esattamente 1: devi includere un valore del gruppo.
Utilizzane uno o più:puoi includere uno o più valori del gruppo, ma devi includerne almeno uno.
Secondo i seguenti termini, un valore è facoltativo:
(Facoltativo) Puoi includere il valore.
Utilizza 0 o 1: puoi includere un valore dal gruppo.
Utilizza 0 o più:puoi includere uno o tutti i valori del gruppo.
Report video
Statistiche di base
Statistiche di base sull'attività utente
Questo report fornisce statistiche relative alle azioni degli utenti su un canale. Puoi filtrare il report in modo che restituisca solo i dati relativi a un video o un paese specifico.
Statistiche di base sull'attività utente per gli stati degli Stati Uniti
Questo rapporto fornisce statistiche relative a un determinato stato degli Stati Uniti o al District of Columbia. Tieni presente che questo report supporta solo un sottoinsieme delle metriche disponibili nel report specifico per paese descritto sopra.
Attività utente per paese per periodi di tempo specifici
Questo report fornisce statistiche relative alle azioni degli utenti su un canale per intervalli di tempo specifici. Puoi filtrare il report in modo che restituisca solo i dati relativi a un video o un paese specifico.
Attività degli utenti negli stati degli Stati Uniti per periodi di tempo specifici
Questo rapporto fornisce statistiche sull'attività degli utenti in un determinato stato degli Stati Uniti o nel District of Columbia. Tieni presente che questo report supporta solo un sottoinsieme delle metriche disponibili nel report specifico per paese descritto sopra.
Questo report fornisce statistiche relative all'attività utente per paese per ogni canale. Puoi filtrare il report in modo che restituisca solo i dati relativi a un video specifico.
Questo rapporto fornisce statistiche sull'attività degli utenti per gli stati degli Stati Uniti e il District of Columbia. Per questo report, devi impostare il valore parametro filters su country==US.
Nota:questo report richiede di impostare il parametro maxResults su un valore intero pari o inferiore a 250. A differenza della maggior parte degli altri report, questo report richiede anche di specificare un valore per il parametro di richiesta sort.
Questo report fornisce statistiche sull'attività utente per città.
I report sui dettagli di riproduzione forniscono statistiche relative ai seguenti attributi di visualizzazione:
Era la visualizzazione di una trasmissione video in diretta o di un video on demand?
Lo spettatore era iscritto al canale proprietario del video?
Su quale prodotto di YouTube è avvenuta la visualizzazione?
Nota: la dimensione e il filtro liveOrOnDemand non possono essere utilizzati insieme alla metrica averageViewPercentage. Pertanto, ciascuna delle seguenti sottosezioni elenca due report. Un report supporta la dimensione (e il filtro) liveOrOnDemand, mentre l'altro supporta la metrica averageViewPercentage.
Attività utente per stato di iscrizione
Questo report fornisce metriche sull'attività utente per gli spettatori iscritti e non iscritti. Le statistiche possono essere raggruppate per periodo di tempo (giorno o mese) e il report può anche essere filtrato per paese, continente o subContinent.
Attività utente per stato di iscrizione per le province
Questo report fornisce metriche sull'attività utente degli spettatori iscritti e non iscritti negli stati degli Stati Uniti o nel District of Columbia. Questo report supporta meno metriche rispetto al report precedente.
Dettagli sulla riproduzione con dimensione temporale facoltativa
La dimensione temporale, giorno o mese, è facoltativa per questi report perché, in ogni caso, devi utilizzare i parametri di richiesta startDate e endDate per specificare l'intervallo di date che verrà incluso nel report. La dimensione, se presente, indica che vuoi che i dati nel report vengano aggregati per giorno, mese e così via.
Dettagli sulla riproduzione con dimensione temporale facoltativa e statistiche liveOrOnDemand
Questo report fornisce statistiche dettagliate sulla riproduzione per intervalli di tempo specifici. Supporta la dimensione (e il filtro) liveOrOnDemand.
Il seguente report è simile al precedente. Aggiunge il supporto per la metrica averageViewPercentage, ma non supporta liveOrOnDemand come dimensione o filtro.
Dettagli sulla riproduzione per provincia con statistiche liveOrOnDemand
Questo rapporto fornisce statistiche dettagliate sulla riproduzione per gli stati degli Stati Uniti e il District of Columbia. Supporta la dimensione (e il filtro) liveOrOnDemand.
Il seguente report è simile al precedente. Aggiunge il supporto per la metrica averageViewPercentage, ma non supporta liveOrOnDemand come dimensione o filtro.
Dettagli sul luogo di visualizzazione (<= 25 risultati)
Nota:questo report richiede di impostare il parametro maxResults su un valore intero pari o inferiore a 25. A differenza della maggior parte degli altri report, questo report richiede anche di specificare un valore per il parametro di richiesta sort.
Questo report identifica i video player incorporati che hanno generato il maggior numero di visualizzazioni o di tempo di visualizzazione per i video di un canale.
Questo report aggrega le statistiche di visualizzazione in base al modo in cui gli spettatori hanno raggiunto i tuoi contenuti video. Ad esempio, indica il numero di visualizzazioni provenienti da una ricerca su Google o da un link a un video correlato.
Nota:questo report richiede di impostare il parametro maxResults su un valore intero pari o inferiore a 25. A differenza della maggior parte degli altri report, questo report richiede anche di specificare un valore per il parametro di richiesta sort.
Questo rapporto aggrega le statistiche di visualizzazione in base ai referrer che hanno generato il maggior numero di visualizzazioni per i contenuti del canale. I referrer sono classificati in base al tipo di sorgente di traffico e la definizione della dimensione insightTrafficSourceDetail identifica le sorgenti di traffico per le quali è disponibile il report. Ad esempio, se imposti il filtro insightTrafficSourceType su ADVERTISING, nel report verranno elencati i tipi di annunci che hanno generato il maggior numero di visualizzazioni o il tempo di visualizzazione per i contenuti del canale.
Nota:questo report è supportato solo per specifiche sorgenti di traffico. Ad esempio, la sorgente di traffico NO_LINK_EMBEDDED non presenta ulteriori dettagli e, pertanto, non supporta questo report. Consulta la definizione di insightTrafficSourceType per informazioni dettagliate sulle sorgenti di traffico che supportano questo report.
Tipo di dispositivo e sistema operativo
Tipo di dispositivo
Questo report aggrega le statistiche di visualizzazione in base al modo in cui gli spettatori hanno raggiunto i tuoi contenuti video. Ad esempio, identifica il numero di visualizzazioni effettuate su dispositivi mobili o console per videogiochi.
Questo report aggrega le statistiche di visualizzazione in base ai sistemi operativi dei visualizzatori. Ad esempio, identifica il numero di visualizzazioni che si sono verificate sui dispositivi Android o sulle PlayStation.
Questo report aggrega le statistiche di visualizzazione in base ai sistemi operativi e ai tipi di dispositivo degli utenti. Ad esempio, identifica il numero di visualizzazioni che si sono verificate sui tablet Android o sui computer Windows.
Ad esempio, un report che utilizza la dimensione subscribedStatus restituisce i dati del viewerPercentage con un aumento del 100% delle visualizzazioni per gli spettatori non iscritti{/10, sommando il 100% delle visualizzazioni in percentuale.{/10viewerPercentage Il valore totale di tutti i campi viewerPercentage del report è pari al 200%.
Puoi utilizzare i filtri per assicurarti che il report contenga solo i dati viewerPercentage per un valore (o una combinazione di valori) per le dimensioni dei dettagli di riproduzione.
Coinvolgimento e condivisione dei contenuti
Questo report fornisce statistiche che mostrano la frequenza di condivisione dei video del canale su diverse piattaforme social.
Questo report misura la capacità di un video di conservare il pubblico. La dimensione elapsedVideoTimeRatio misura la quantità di video trascorso per i valori delle metriche corrispondenti. Le metriche audienceWatchRatio e relativeRetentionPerformance forniscono due misurazioni che mostrano l'efficacia con cui il video fidelizza il pubblico. Il primo è un valore assoluto, mentre il secondo mostra il rendimento del video rispetto ad altri video di YouTube di durata simile.
Nota:i report sulla fidelizzazione del pubblico non supportano la possibilità di specificare un elenco di valori separati da virgole per il filtro video; il valore deve specificare un singolo ID video.
Nota:questi report richiedono di impostare il parametro maxResults su un valore intero pari o inferiore a 200. Prima del 1° gennaio 2013, i dati sono disponibili solo per i primi 10 video. A differenza della maggior parte degli altri report, questi report richiedono anche di specificare un valore per il parametro di richiesta sort.
Video principali con filtri regionali facoltativi (<= 200 risultati)
Questo report elenca i video principali del canale. Il report può essere filtrato in modo da elencare i video principali per paese, continente o subContinent.
Questo report elenca i video principali del canale in un determinato stato degli Stati Uniti o nel District of Columbia. Tieni presente che questo report supporta solo un sottoinsieme delle metriche disponibili nel report specifico per paese descritto sopra.
Video principali per gli spettatori iscritti o non iscritti(<= 200 risultati)
Questo report elenca i video principali del canale per gli spettatori iscritti o non iscritti. Il report può essere filtrato in modo da elencare i video principali per paese, continente o subContinent. Il report precedente ti consente di recuperare i video principali in un determinato stato degli Stati Uniti per gli spettatori iscritti o non iscritti, ma supporta un numero inferiore di metriche rispetto a questo report.
Video principali per prodotto YouTube (<= 200 risultati)
Questo report elenca i video principali del canale e supporta i filtri geografici e i dettagli di riproduzione. Questo report è simile al precedente, ma supporta un numero inferiore di metriche e aggiunge il supporto per il filtro youtubeProduct.
I report sulle playlist contengono metriche relative alle attività utente relative ai video nelle playlist del proprietario del canale. Sono disponibili due versioni di questi report e, per ogni report disponibile, le seguenti sezioni contengono una descrizione di ogni versione:
La scheda Consigliato in ogni sezione descrive il formato di richiesta API preferito per recuperare il report corrispondente. I report consigliati supportano un insieme ampliato di metriche che includono sia metriche video aggregate sia metriche in-playlist. Questo formato di richiesta non utilizza la dimensione isCurated.
La scheda Utilizzo di isCurated in ogni sezione descrive un formato di richiesta API precedente
in cui è obbligatoria la dimensione isCurated. Questi report supportano solo le metriche in-playlist. Tieni presente che la dimensione isCurated è stata ritirata per tutti i report. La nota di avviso riportata di seguito spiega la pianificazione del ritiro.
La seguente nota di avviso spiega in modo più dettagliato le modifiche tra le due versioni dei report.
Metriche video aggregate
Queste metriche forniscono metriche relative all'attività utente e alle impressioni aggregate per tutti i video contenuti nella playlist che sono anche di proprietà del canale proprietario della playlist. Le metriche per i video di proprietà di altri canali non vengono calcolate nell'aggregazione. Di conseguenza, se un canale crea una
playlist che contiene solo video di proprietà di altri canali, i report per queste playlist non
forniranno valori per queste metriche.
Consulta la sezione delle metriche delle playlist supportate per un elenco delle metriche aggregate relative ai video supportate da YouTube.
Metriche in-playlist
Queste metriche riflettono l'attività e il coinvolgimento degli utenti nel contesto della pagina della playlist. Queste metriche includono le visualizzazioni di tutti i video contenuti nella playlist, indipendentemente dal canale di sua proprietà, ma conteggiano solo le visualizzazioni che si sono verificate nel contesto della playlist.
Questo report fornisce statistiche relative alle interazioni degli utenti con i video nelle playlist del canale. Puoi filtrare il report in modo che restituisca solo i dati relativi a una playlist specifica.
Questo report fornisce statistiche relative alle interazioni degli utenti con i video nelle playlist del canale. Puoi filtrare il report in modo che restituisca solo i dati relativi a una playlist specifica.
Questo report fornisce statistiche sull'attività delle playlist per gli stati degli Stati Uniti e il District of Columbia.
Per questo report, devi filtrare i risultati in modo che restituiscano dati solo per gli Stati Uniti.
Dettagli sul luogo di visualizzazione (<= 25 risultati)
Nota:questo report richiede di impostare il parametro maxResults su un valore intero pari o inferiore a 25. A differenza della maggior parte degli altri report, questo report richiede anche di specificare un valore per il parametro di richiesta sort.
Questo report identifica i video player incorporati che hanno generato il maggior numero di visualizzazioni o il tempo di visualizzazione per i video nelle playlist del canale.
Questo report aggrega le statistiche di visualizzazione in base al modo in cui gli spettatori hanno raggiunto i contenuti delle tue playlist.
Ad esempio, indica il numero di visualizzazioni che hanno origine da una ricerca su Google.
Nota: per questo report è necessario impostare il parametro maxResults su un valore intero pari o inferiore a 25. A differenza della maggior parte degli altri report, questo report richiede anche di specificare un valore per il parametro di richiesta sort.
Questo report aggrega le statistiche sulle visualizzazioni in base ai referrer che hanno generato il maggior numero di visualizzazioni per i video nelle playlist del canale. I referrer sono classificati in base al tipo di sorgente di traffico e la definizione della dimensione insightTrafficSourceDetail identifica le sorgenti di traffico per le quali è disponibile il report.
Ad esempio, se imposti il filtro insightTrafficSourceType su ADVERTISING, nel report verranno elencati i tipi di annunci che hanno generato il maggior numero di visualizzazioni o il tempo di visualizzazione per le playlist del canale.
Nota:questo report è supportato solo per specifiche sorgenti di traffico. Ad esempio, la sorgente di traffico NO_LINK_EMBEDDED non presenta ulteriori dettagli e, pertanto, non supporta questo report. Consulta la definizione di insightTrafficSourceType per informazioni dettagliate sulle sorgenti di traffico che supportano questo report.
Tipo di dispositivo e sistema operativo
Tipo di dispositivo
Questo report aggrega le statistiche di visualizzazione in base al modo in cui gli spettatori hanno raggiunto i video nelle tue
playlist. Ad esempio, identifica il numero di visualizzazioni effettuate su dispositivi mobili o console per videogiochi.
Questo report aggrega le statistiche di visualizzazione in base ai sistemi operativi dei visualizzatori. Ad esempio, identifica il numero di visualizzazioni che si sono verificate sui dispositivi Android o sulle PlayStation.
Questo report aggrega le statistiche di visualizzazione in base ai sistemi operativi e ai tipi di dispositivo degli utenti.
Ad esempio, identifica il numero di visualizzazioni che hanno avuto luogo su tablet Android o dispositivi desktop Windows.
Nota:i valori viewerPercentage in questo report non sono normalizzati per valori diversi della dimensione dei dettagli della riproduzione subscribedStatus.
Ad esempio, un report che utilizza la dimensione subscribedStatus restituisce i dati del viewerPercentage che hanno una somma fino al 100% per le visualizzazioni degli iscritti e quelli delviewerPercentage per una percentuale fino al 100% per le visualizzazioni non iscritti Il valore totale di tutti i campi viewerPercentage del report è pari al 200%.
Puoi utilizzare i filtri per assicurarti che il report contenga solo i dati viewerPercentage per un valore delle dimensioni subscribedStatus.
Playlist principali
Nota:questi report richiedono di impostare il parametro maxResults su un valore intero pari o inferiore a 200. Prima del 1° gennaio 2013, i dati sono disponibili solo per le 10 playlist principali. A differenza della maggior parte degli altri report, questi report richiedono anche di specificare un valore per il parametro di richiesta sort.
Questo report elenca le playlist principali del canale in base ai criteri di filtro e ordinamento specificati.
Nota:i report sul rendimento degli annunci richiedono un token di autorizzazione che conceda l'accesso all'ambito https://www.googleapis.com/auth/yt-analytics-monetary.readonly.
I report sul rendimento degli annunci forniscono metriche basate sulle impressioni per gli annunci che sono stati pubblicati durante le riproduzioni video. Queste metriche prendono in considerazione ogni impressione dell'annuncio e ogni riproduzione video può generare più impressioni.
Le metriche di rendimento degli annunci basate sulle impressioni sono:
Inoltre, alcuni report sui video supportano le seguenti metriche sul rendimento degli annunci basate sulla riproduzione. Tuttavia, queste metriche non sono incluse nei report sul rendimento degli annunci.
