Questa pagina elenca i report che i proprietari di canali possono recuperare con l'API YouTube Analytics. I report sul canale forniscono metriche sull'attività utente per un canale specifico e misurano, ad esempio, visualizzazioni, valutazioni e numero di iscritti dei video.
I report sui video forniscono statistiche su tutta l'attività utente relativa ai video di un canale.
I report sulle playlist forniscono statistiche specifiche relative alle visualizzazioni dei video che si verificano 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 pubblicati durante la riproduzione dei video. La sezione Report sul rendimento degli annunci spiega i due tipi di metriche sul rendimento degli annunci supportati dall'API.
Recuperare un report
Per recuperare un report sul canale, devi impostare il valore del parametro ids nella richiesta API su uno dei seguenti valori:
channel==MINE: l'API restituisce i dati del canale YouTube dell'utente autenticato.
channel==CHANNEL_ID: imposta CHANNEL_ID sull'ID canale univoco del canale per cui stai recuperando i dati. L'utente che autorizza la richiesta deve essere il proprietario del canale.
Al momento, l'ID canale è una stringa che inizia con le lettere UC, anche se il formato è soggetto a modifiche. Puoi trovare l'ID del tuo canale nella pagina Impostazioni avanzate dell'account del tuo canale YouTube oppure puoi recuperarlo tramite programmazione utilizzando il metodo YouTube Data API'schannels.list.
Autorizzazione
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 all'API YouTube Analytics utilizzano i seguenti ambiti di autorizzazione:
Visualizzare i report di YouTube Analytics per i contenuti di YouTube. Questo ambito fornisce l'accesso alle metriche sull'attività utente, come i conteggi delle visualizzazioni e delle valutazioni.
Visualizzare i report di YouTube Analytics relativi al valore monetario per i contenuti di YouTube. Questo ambito fornisce l'accesso alle metriche sull'attività utente e alle metriche stimate relative alle entrate e al rendimento degli annunci.
https://www.googleapis.com/auth/youtube
Gestire il tuo account YouTube. Nell'API YouTube Analytics, i proprietari dei canali utilizzano questo ambito per gestire i gruppi e gli elementi di gruppo di YouTube Analytics.
https://www.googleapis.com/auth/youtubepartner
Visualizzare e gestire le risorse di YouTube e i relativi contenuti su YouTube. Nell'API di YouTube Analytics, i proprietari di contenuti utilizzano questo ambito per gestire i gruppi e gli elementi di gruppo di YouTube Analytics.
Nota:le metriche relative alle entrate stimate e al rendimento degli annunci non sono attualmente supportate per i report sul canale. Di conseguenza, l'ambito https://www.googleapis.com/auth/yt-analytics-monetary.readonly al momento non concede l'accesso ai dati monetari in questi report.
Filtri
Le tabelle che spiegano i report supportati identificano i filtri che possono essere utilizzati per ciascun report. Nelle tabelle, i filtri indicati 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 aggiungerlo 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 di come filtrare i risultati dell'API in base a un valore o a un insieme di valori specifici.
Informazioni sulle tabelle dei report
Questa sezione spiega la formattazione e la terminologia utilizzata nelle tabelle che definiscono i report supportati dall'API. La seguente tabella elenca le dimensioni, le metriche e i filtri supportati per il
report Video: dettagli sulla riproduzione che utilizza la dimensione Tempo e la metrica averageViewPercentage.
La tabella contiene due righe per le dimensioni, una riga per le metriche e tre righe 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 rispetti le regole di utilizzo riportate nella tabella. Ad esempio, i valori validi del parametro dimensions
per questo report includono:
dimensions=day
dimensions=day,subscribedStatus
dimensions=month,subscribedStatus,youtubeProduct
dimensions=month,youtubeProduct
Tuttavia, il valore del parametro day,month non è valido perché utilizza due dimensioni basate sul tempo e la richiesta deve utilizzare 0 o 1.
Terminologia delle tabelle dei report
Le tabelle utilizzano la seguente terminologia per indicare se le dimensioni sono obbligatorie o facoltative:
Questi termini indicano che è necessario un valore:
Obbligatorio: devi includere il valore.
Utilizza esattamente 1: devi includere un valore del gruppo.
Utilizza 1 o più: puoi includere uno o tutti i valori del gruppo, ma devi includerne almeno uno.
Questi termini indicano che un valore è facoltativo:
Facoltativo:puoi scegliere di includere il valore.
Utilizza 0 o 1:hai la possibilità di includere un valore del gruppo.
Utilizza 0 o più: hai la possibilità di 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 a un paese specifico.
Statistiche di base sull'attività utente per gli stati degli Stati Uniti
Questo report fornisce statistiche per un determinato stato degli Stati Uniti o per il Distretto di 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 a un paese specifico.
Attività utente negli stati USA per periodi di tempo specifici
Questo report fornisce statistiche relative all'attività utente per un determinato stato degli Stati Uniti o per il Distretto di Columbia. Tieni presente che questo report supporta solo un sottoinsieme delle metriche disponibili nel report specifico per paese descritto sopra.
Questo report fornisce statistiche sull'attività utente per paese per un canale. Puoi filtrare il report in modo che restituisca solo i dati relativi a un video specifico.
Questo report fornisce statistiche sull'attività utente per gli stati degli Stati Uniti e per il Distretto di Columbia.
Per questo report, devi impostare il valore del 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 richiede anche di specificare un valore per il parametro di richiesta sort.
Questo report fornisce statistiche sull'attività utente per città.
Questo report fornisce statistiche sull'attività utente per area di mercato designata (DMA). Per questo report,
devi impostare il valore del parametro filters su country==US o
filtrare in base a una determinata provincia (stato degli Stati Uniti).
I report dettagliati sulla riproduzione forniscono statistiche relative ai seguenti attributi di visualizzazione:
Si trattava della 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 YouTube è avvenuta la visualizzazione?
Nota: la dimensione e il filtro liveOrOnDemand non possono essere utilizzati in combinazione con la metrica averageViewPercentage. Di conseguenza, 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ò essere filtrato anche per paese, continente o subContinent.
Attività utente per stato dell'abbonamento per le province
Questo report fornisce metriche sull'attività utente per gli spettatori iscritti e non iscritti negli stati degli Stati Uniti o nel Distretto di 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 coperto dal 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 report seguente è simile al precedente. Aggiunge il supporto della metrica averageViewPercentage, ma non supporta liveOrOnDemand come dimensione o filtro.
Dettagli sulla riproduzione per provincia con le statistiche liveOrOnDemand
Questo report fornisce statistiche dettagliate sulla riproduzione per gli stati degli Stati Uniti e per il Distretto di Columbia. Supporta la dimensione (e il filtro) liveOrOnDemand.
Il report seguente è simile al precedente. Aggiunge il supporto della 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 richiede anche di specificare un valore per il parametro di richiesta sort.
Questo report identifica i player video 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 sulle visualizzazioni in base al modo in cui gli spettatori hanno raggiunto i tuoi contenuti video. Ad esempio, identifica il numero di visualizzazioni generate da una ricerca su Google o da un link a un video correlato.
Nota: questo report restituisce un errore se il prodotto tra Numero di video sottoposti a query x Numero di giorni nell'intervallo di date supera 50.000. Ad esempio, una query
che recupera i dati per 500 ID video può richiedere dati per un massimo di 100 giorni. Per ridurre il
numero di righe restituite da una richiesta, suddividi la query in più query che specificano meno
video o impostano intervalli di date più brevi.
Dettagli sulla sorgente di traffico (<= 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 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 contenuti del canale. I referrer vengono classificati in base al tipo di sorgente di traffico e la definizione della dimensione insightTrafficSourceDetail identifica le sorgenti di traffico per cui è disponibile il report. Ad esempio, se imposti il filtro insightTrafficSourceType su ADVERTISING, il report elenca i tipi di annunci che hanno generato il maggior numero di visualizzazioni o il maggior tempo di visualizzazione per i contenuti del canale.
Nota:questo report è supportato solo per sorgenti di traffico specifiche. VIDEO_REMIXES, NOTIFICATION, END_SCREEN, CAMPAIGN_CARD, VIDEO_REMIXES e NO_LINK_EMBEDDED sono alcune delle sorgenti di traffico non supportate.
Tipo di dispositivo e sistema operativo
Tipo di dispositivo
Questo report aggrega le statistiche sulle visualizzazioni in base al modo in cui gli spettatori hanno raggiunto i tuoi contenuti video. Ad esempio, identifica il numero di visualizzazioni generate su dispositivi mobili o console per videogiochi.
Questo report aggrega le statistiche sulle visualizzazioni in base ai sistemi operativi degli spettatori. Ad esempio, identifica il numero di visualizzazioni generate su dispositivi Android o PlayStation.
Questo report aggrega le statistiche sulle visualizzazioni in base ai sistemi operativi e ai tipi di dispositivi degli spettatori. Ad esempio, identifica il numero di visualizzazioni generate su tablet Android o su computer Windows.
Ad esempio, un report che utilizza la dimensione subscribedStatus restituisce dati di viewerPercentage che sommati ammontano al 100% per le visualizzazioni degli utenti iscritti e dati di viewerPercentage che sommati ammontano al 100% per le visualizzazioni degli utenti non iscritti. Il valore totale di tutti i campi viewerPercentage nel report è pari al 200%.
Puoi utilizzare i filtri per assicurarti che il report contenga solo i dati di viewerPercentage per un valore (o una combinazione di valori) per le dimensioni dei dettagli di riproduzione.
Coinvolgimento e condivisione di contenuti
Questo report fornisce statistiche che mostrano la frequenza con cui i video del canale sono stati condivisi su diverse piattaforme social.
Questo report misura la capacità di un video di fidelizzare il pubblico e mostra anche la frequenza con cui parti specifiche di un video sono state guardate. La dimensione elapsedVideoTimeRatio misura il tempo trascorso del video per i valori delle metriche corrispondenti. Le metriche possono essere suddivise in due categorie:
Fidelizzazione del pubblico
Queste metriche mostrano la capacità del video di fidelizzare il pubblico.
audienceWatchRatio è un rapporto che mette a confronto il numero di volte in cui una
parte di un video è stata visualizzata con il numero totale di visualizzazioni del video.
relativeRetentionPerformance mostra il grado di fidelizzazione del pubblico di un video
durante la riproduzione rispetto ad altri video di YouTube di durata simile.
Statistiche granulari dello smartwatch
Queste metriche forniscono informazioni sulla frequenza con cui parti specifiche di un video sono state guardate.
startedWatching indica la frequenza con cui gli spettatori hanno iniziato a guardare un video
durante un determinato segmento del video.
stoppedWatching indica la frequenza con cui gli spettatori hanno smesso di guardare un video
durante un determinato segmento.
totalSegmentImpressions indica la frequenza con cui un determinato segmento del
video è stato visualizzato.
Nota:questo report non supporta la possibilità di specificare un elenco di valori separati da virgola per il filtro video. Il valore deve specificare un singolo ID video.
Questo report mostra gli spettatori simultanei in una determinata posizione per un singolo video trasmesso in live streaming.
Il filtro specifica il video. La dimensione Posizione in genere rappresenta un singolo minuto.
Nota:per questi report devi impostare il parametro maxResults su un valore intero pari o inferiore a 200. I dati precedenti al 1° gennaio 2013 sono disponibili solo per i 10 video più popolari. A differenza della maggior parte degli altri report, questi richiedono anche di specificare un valore per il parametro di richiesta sort.
Video più popolari 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 più popolari del canale in un determinato stato degli Stati Uniti o nel Distretto di Columbia. Tieni presente che questo report supporta solo un sottoinsieme delle metriche disponibili nel report specifico per paese descritto sopra.
Video più popolari tra gli spettatori iscritti o non iscritti(<= 200 risultati)
Questo report elenca i video più popolari 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 più popolari in un determinato stato degli Stati Uniti per gli spettatori iscritti o non iscritti, ma supporta meno metriche rispetto a questo report.
Video più popolari per prodotto YouTube (<= 200 risultati)
Questo report elenca i video più popolari del canale e supporta i dettagli sulla riproduzione e i filtri geografici. Questo report è simile al precedente, ma supporta meno metriche e aggiunge il supporto per il filtro youtubeProduct.
I report sulle playlist contengono metriche relative all'attività degli utenti in relazione ai video delle 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 della richiesta API preferito per recuperare il report corrispondente. I report consigliati supportano un insieme più ampio di metriche
che include sia le metriche video aggregate sia le
metriche all'interno delle playlist. Questo formato di richiesta non utilizza la dimensione
isCurated.
La scheda Utilizzo di isCurated in ogni sezione descrive un formato precedente della richiesta dell'API in cui è obbligatoria la dimensione isCurated. Questi report supportano solo le metriche all'interno della playlist. Tieni presente che la dimensione
isCurated è stata ritirata per tutti i report. La nota di avviso riportata di seguito
spiega il programma di ritiro.
La seguente nota di avviso spiega in modo più dettagliato le modifiche tra le due versioni del report.
Metriche video aggregate
Queste metriche forniscono metriche relative all'attività utente e alle impressioni aggregate per tutti i video
della playlist che sono di proprietà del canale che possiede la playlist. Le metriche relative ai video di proprietà di altri canali non vengono calcolate nell'aggregazione. Di conseguenza, se un canale crea una
playlist contenente solo video di proprietà di altri canali, i report relativi a queste playlist non
forniranno valori per queste metriche.
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 della playlist, indipendentemente dal canale a cui appartengono, ma
conteggiano solo le visualizzazioni generate 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 per il Distretto di Columbia.
Per questo report, devi filtrare i risultati in modo da restituire i 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 richiede anche di specificare un valore per il parametro di richiesta sort.
Questo report identifica i player video incorporati che hanno generato il maggior numero di visualizzazioni o tempo di visualizzazione
per i video nelle playlist del canale.
Questo report aggrega le statistiche sulle visualizzazioni in base al modo in cui gli spettatori hanno raggiunto i contenuti della tua playlist.
Ad esempio, identifica il numero di visualizzazioni generate da una ricerca su Google.
Dettagli sulla sorgente di traffico (<= 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 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 vengono 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, il report elenca i tipi di annunci che hanno generato il maggior numero di visualizzazioni o il maggior tempo di visualizzazione per le playlist del canale.
Nota:questo report è supportato solo per sorgenti di traffico specifiche. VIDEO_REMIXES, NOTIFICATION, END_SCREEN, CAMPAIGN_CARD, VIDEO_REMIXES e NO_LINK_EMBEDDED sono alcune delle sorgenti di traffico non supportate.
Tipo di dispositivo e sistema operativo
Tipo di dispositivo
Questo report aggrega le statistiche sulle visualizzazioni in base al modo in cui gli spettatori hanno raggiunto i video delle tue playlist. Ad esempio, identifica il numero di visualizzazioni generate su dispositivi mobili o console per videogiochi.
Questo report aggrega le statistiche sulle visualizzazioni in base ai sistemi operativi degli spettatori. Ad esempio, identifica il numero di visualizzazioni registrate su dispositivi Android o PlayStation.
Questo report aggrega le statistiche sulle visualizzazioni in base ai sistemi operativi e ai tipi di dispositivi degli spettatori.
Ad esempio, identifica il numero di visualizzazioni generate su tablet Android o computer Windows.
Nota:i valori di viewerPercentage in questo report non sono normalizzati per valori diversi della dimensione dei dettagli di riproduzione subscribedStatus.
Ad esempio, un report che utilizza la dimensione subscribedStatus restituisce dati di viewerPercentage che sommati ammontano al 100% per le visualizzazioni con iscrizione e dati di viewerPercentage che sommati ammontano al 100% per le visualizzazioni senza iscrizione. Il valore totale di tutti i campi viewerPercentage nel report è pari al 200%.
Puoi utilizzare i filtri per assicurarti che il report contenga solo i dati di viewerPercentage per un valore delle dimensioni subscribedStatus.
Playlist principali
Nota:per questi report devi impostare il parametro maxResults su un valore intero pari o inferiore a 200. I dati precedenti al 1° gennaio 2013 sono disponibili solo per le 10 playlist principali. A differenza della maggior parte degli altri report, questi richiedono anche di specificare un valore per il parametro di richiesta sort.
Questo report elenca le playlist più popolari del canale in base ai criteri di filtro e ordinamento specificati.
Nota:i report sul rendimento degli annunci richiedono un token di autorizzazione che concede 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 pubblicati durante la riproduzione dei video. Queste metriche tengono conto di ogni impressione dell'annuncio e ogni riproduzione del video può generare più impressioni.
Le metriche sul rendimento degli annunci basate sulle impressioni sono:
Inoltre, alcuni report video supportano le seguenti metriche sul rendimento degli annunci basate sulla riproduzione. Tuttavia, queste metriche non sono incluse nei report sul rendimento degli annunci.
