Nota:Content owner reports are only accessible to YouTube content partners who participate in the YouTube Partner Program.
Questa pagina elenca i report che i proprietari dei contenuti possono recuperare con l'API YouTube Analytics. I report dei proprietari dei contenuti contengono le metriche relative ai canali collegati a un proprietario dei contenuti YouTube specifico. Le metriche sono misurazioni individuali dell'attività utente, del rendimento degli annunci o delle entrate stimate.
I report sui video contengono metriche sull'attività utente, sul rendimento degli annunci e sulle entrate stimate per i video sui canali di un proprietario dei contenuti.
I report sulle playlist forniscono statistiche specifiche relative alle visualizzazioni dei video che si verificano nel contesto di una playlist. I report sulle playlist utilizzano molte delle dimensioni e dei filtri dei report sui video.
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 del proprietario dei contenuti, chiama il metodo reports.query dell'API e imposta il valore del parametro ids nella richiesta API su contentOwner==OWNER_NAME, dove OWNER_NAME specifica l'ID del proprietario dei contenuti. Chiedi al tuo Partner Manager se hai dubbi sul valore.
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 contrassegnate da un asterisco (*) richiedono un token di autorizzazione che consenta l'accesso all'ambito https://www.googleapis.com/auth/yt-analytics-monetary.readonly.
Filtri
Tutte le richieste API per recuperare i report dei proprietari di contenuti devono filtrare i dati utilizzando la dimensione video, la dimensione channel, la dimensione isCurated o una combinazione supportata delle dimensioni claimedStatus e uploaderType. Le combinazioni supportate sono elencate nella definizione della dimensione uploaderType.
Le tabelle che spiegano i report supportati identificano i filtri che possono essere utilizzati per un determinato report. Nelle descrizioni, i filtri mostrati tra parentesi sono facoltativi. Ad esempio, se un report elenca video(,country) come opzione di filtro, il report può essere filtrato in modo da includere solo i dati relativi a un video specifico o solo i dati relativi a un video specifico in un paese specifico.
L'API supporta anche la possibilità di specificare più valori per i filtri video, playlist e channel. 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.
Importante: tutte le richieste API per recuperare i report sui video dei proprietari dei contenuti devono filtrare i dati utilizzando la dimensione video, la dimensione channel, la dimensione group o una combinazione supportata delle dimensioni claimedStatus e uploaderType. (alcuni report non supportano tutte queste opzioni). Le combinazioni supportate, elencate anche nella definizione della dimensione uploaderType, sono:
uploaderType==self
claimedStatus==claimed
claimedStatus==claimed;uploaderType==self
claimedStatus==claimed;uploaderType==thirdParty
Report video
Statistiche di base
Statistiche di base (inclusi i conteggi degli iscritti)
Questo report fornisce statistiche relative alle azioni degli utenti su tutti i canali di un proprietario dei contenuti. Puoi filtrare il report in modo che restituisca solo i dati relativi a un video o a un paese specifico. Può essere utilizzata anche per recuperare solo le statistiche relative ai contenuti rivendicati, inclusi quelli caricati dal proprietario dei contenuti, da terze parti o da entrambi.
Statistiche di base 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.
Questo report fornisce statistiche relative alle azioni degli utenti su tutti i canali di un proprietario dei contenuti 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 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 tutti i canali di un proprietario di contenuti. Puoi filtrare il report in modo che restituisca solo i dati relativi a un video o un canale 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à.
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?
Tecnicamente, le dimensioni dei dettagli sulla riproduzione supportate da questi report sono tutte facoltative. Se non includi le dimensioni dei dettagli di riproduzione nella richiesta, il report restituito sarà simile a uno dei report sulle statistiche di base, in base al tempo o sulla geografia degli utenti.
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 video player incorporati che hanno generato il maggior numero di visualizzazioni o il maggior tempo di visualizzazione per i contenuti di un proprietario di contenuti. Quando recuperi questo report, devi impostare il filtro insightPlaybackLocationType su EMBEDDED.
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 proprietario. 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 proprietario.
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 tipo di dispositivo utilizzato dagli spettatori per guardare i tuoi contenuti. Ad esempio, identifica il numero di visualizzazioni che si sono verificate su tablet 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.
Nota:i valori di viewerPercentage in questo report non sono normalizzati per valori diversi della dimensione dei dettagli di riproduzione subscribedStatus.
Questo report misura la capacità di un video di fidelizzare il pubblico. La dimensione elapsedVideoTimeRatio misura la durata del video trascorsa per i valori delle metriche corrispondenti. Le metriche audienceWatchRatio e relativeRetentionPerformance forniscono due misurazioni che mostrano la capacità del video di fidelizzare 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 virgola per il filtro video; il valore deve specificare un singolo ID video.
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 in generale, per paese, continente o subcontinente (<= 200 risultati)
Questo report elenca i video principali del proprietario dei contenuti in base ai criteri di filtro e ordinamento specificati.
Video più popolari in generale per stato degli Stati Uniti (<= 200 risultati)
Questo report elenca i video più popolari del proprietario dei contenuti 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 tra 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 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.
Video più popolari con filtri dei dettagli sulla riproduzione (<= 200 risultati)
Questo report elenca i video più popolari del proprietario dei contenuti, filtrando i dati in base a una o più dimensioni relative ai dettagli di riproduzione: liveOrOnDemand, subscribedStatus e youtubeProduct. Il report supporta anche i filtri per regione.
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 delle playlist sui canali di un proprietario dei contenuti. Il report non contiene dimensioni obbligatorie.
Questo report fornisce statistiche relative alle interazioni degli utenti con i video delle playlist dei canali di un proprietario dei contenuti in intervalli di tempo specifici. Puoi filtrare il report in modo da visualizzare solo i dati relativi a una playlist o a un canale specifici.
Questo report fornisce statistiche sull'attività delle playlist per gli stati degli Stati Uniti e per il Distretto di Columbia. Per questo report, includi country==US nel valore del parametro filters.
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 video player incorporati che hanno generato il maggior numero di visualizzazioni o di tempo di visualizzazione per le playlist di un proprietario di contenuti.
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 o dalla pagina di un canale.
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 le playlist del proprietario dei contenuti. 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 di tempo di visualizzazione per le playlist del proprietario dei contenuti.
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 per le playlist
Questo report aggrega le statistiche sulle visualizzazioni in base al tipo di dispositivo utilizzato dagli spettatori per guardare i contenuti della tua 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 di playlist registrate su dispositivi Android o PlayStation.
Sistema operativo e tipo di dispositivo per le playlist
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 di playlist che si sono verificate su tablet Android o su computer Windows.
Nota: i valori di viewerPercentage in questo report non sono normalizzati per valori o combinazioni di valori diversi per le dimensioni dei dettagli di riproduzione (subscribedStatus e youtubeProduct).
Ad esempio, un report che utilizza la dimensione subscribedStatus restituisce dati di viewerPercentage che sommati ammontano al 100% per le visualizzazioni di utenti iscritti e dati di viewerPercentage che sommati ammontano al 100% per le visualizzazioni di 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.
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 proprietario dei contenuti 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.
