Dimensions

Questo documento definisce le dimensioni supportate dall'API YouTube Analytics. Questa API supporta query mirate in tempo reale per generare report personalizzati di YouTube Analytics.

Le dimensioni sono criteri comuni utilizzati per aggregare i dati, ad esempio la data in cui si è verificata l'attività dell'utente o il paese in cui si trovavano gli utenti.

Ogni report sulle query identifica le dimensioni che supporta. Ad esempio, quando recuperi l'attività utente per ora, scegli il periodo di tempo per il quale verranno riportati i dati: giorno o mese. In qualsiasi report, ogni riga di dati ha una combinazione unica di valori di dimensione.

Per recuperare un report sulle query, chiama il metodo reports.query dell'API YouTube Analytics. Nella richiesta, utilizza il parametro dimensions per specificare le dimensioni che YouTube utilizzerà per calcolare i valori delle metriche nei report.

Dimensioni principali

Sebbene l'API YouTube Analytics sia soggetta alle Norme di ritiro definite nei Termini di servizio, le dimensioni non principali (e le metriche non principali) non sono soggette alle norme. Nelle definizioni di questa pagina, qualsiasi dimensione che è una dimensione principale è identificata esplicitamente come tale.

Il seguente elenco identifica le dimensioni principali dell'API.

Per saperne di più, consulta l'elenco delle API di YouTube soggette alle norme sul ritiro.

Filtri

Tutti i report sulle query supportano i filtri. I filtri identificano i valori delle dimensioni che devono essere presenti nel set di dati recuperato. Pertanto, limitano una risposta API in modo che includa solo i dati corrispondenti a un determinato valore o insieme di valori. Ad esempio, anziché recuperare le metriche sull'attività utente per tutti i paesi, puoi utilizzare un filtro per recuperare solo i dati di un determinato paese.

In una richiesta per recuperare un report query, il parametro di richiesta facoltativo filters specifica i valori di dimensione per i quali vuoi filtrare i dati. Ad esempio, per recuperare le metriche sull'attività utente per l'Europa, imposta il valore parametro filters su continent==150.

Importante:le richieste API per recuperare i report dei proprietari dei contenuti devono filtrare i dati utilizzando una delle dimensioni dell'entità di reporting o una combinazione supportata delle dimensioni claimedStatus e uploaderType.

Dimensioni

Le sezioni seguenti definiscono le dimensioni utilizzate nei report sulle query dell'API YouTube Analytics. Se non diversamente specificato, queste dimensioni vengono utilizzate nei report canale e proprietario dei contenuti. Vengono identificate anche le dimensioni che possono essere utilizzate solo come filtri.

Risorse

Queste dimensioni corrispondono alle risorse che i canali e i proprietari dei contenuti gestiscono su YouTube:

Nota:l'API ti consente di specificare più valori per le dimensioni video, playlist e channel quando vengono utilizzate come filtri. Per farlo, imposta il valore parametro filters su un elenco separato da virgole degli ID di video, playlist o canali per i quali la risposta dell'API deve essere filtrata. Il valore parametro può specificare fino a 500 ID.

video (dimensione principale)
L'ID di un video di YouTube. Nell'API YouTube Data, questo è il valore della proprietà id di una risorsa video. This is a core dimension and is subject to the Deprecation Policy.
playlist
L'ID di una playlist di YouTube. Nell'API YouTube Data, questo è il valore della proprietà id di una risorsa playlist.
canale (dimensione principale) (utilizzata solo nei report dei proprietari dei contenuti)
L'ID di un canale YouTube. Nell'API YouTube Data, questo è il valore della proprietà id di una risorsa channel. This is a core dimension and is subject to the Deprecation Policy.

La dimensione channel viene spesso utilizzata nei report dei proprietari dei contenuti perché questi report in genere aggregano i dati di più canali.
group (solo filtro)
L'ID di un gruppo di YouTube Analytics. Puoi recuperare questo valore utilizzando il metodo groups.list dell'API YouTube Analytics. Quando utilizzi il filtro group, la risposta dell'API contiene i dati di tutti i video, le playlist o i canali del gruppo.

Esempi

Le seguenti richieste di esempio utilizzano dimensioni o filtri dell'entità di reporting:

  • Esempi di canali

    • Statistiche di base
      • Top 10: i video più guardati di un canale
      • I 10 video con le percentuali di clic sulle annotazioni più alte per i video più visualizzati di un canale
      • Statistiche per una playlist specifica
      • Top 10: le playlist più viste di un canale
    • Area geografica
      • Top 10: i video più visti in un paese specifico
      • Top 10: i video più visti in Europa

  • Esempi di proprietari dei contenuti

    • Statistiche di base
      • Top 10 - Most viewed videos for a content owner
      • Top 10 - Most watched videos for a content owner
      • Top 10 - Most viewed videos for a content owner's channel
      • I 10 video con le percentuali di clic sulle annotazioni più alte per i video più visualizzati di un canale
      • Top 10: le playlist più viste per un proprietario dei contenuti
    • Area geografica
      • Top 10: video più guardati in Europa per un proprietario dei contenuti
      • Top 10: le playlist più create negli Stati Uniti

Aree geografiche

Queste dimensioni identificano una regione geografica associata all'attività utente, al rendimento degli annunci o alle metriche sulle entrate stimate.

country (dimensione principale)
Il paese associato alle metriche nella riga del report. Il valore della dimensione è un codice paese ISO 3166-1 di due lettere, ad esempio US, CN (Cina) o FR (Francia). Il codice paese ZZ viene utilizzato per generare report sulle metriche per le quali YouTube non è riuscito a identificare il paese associato. This is a core dimension and is subject to the Deprecation Policy.
province
Lo stato o il territorio degli Stati Uniti associato alle metriche nella riga del report. Il valore della dimensione è un codice ISO 3166-2 che identifica uno stato degli Stati Uniti o il Distretto di Columbia, ad esempio US-MI (Michigan) o US-TX (Texas). Il codice provincia US-ZZ viene utilizzato per generare report sulle metriche per le quali YouTube non è riuscito a identificare lo stato degli Stati Uniti associato. Quando una richiesta API include province nel valore del parametro dimensions, la richiesta deve anche limitare i dati agli Stati Uniti includendo country==US nel valore del parametro filters.

Nota:questa dimensione non supporta i valori ISO 3166-2 che identificano le aree periferiche degli Stati Uniti, in quanto questi territori hanno anche i propri codici paese ISO 3166-1. Inoltre, non supporta le suddivisioni di paesi diversi dagli Stati Uniti.

dma
L'identificatore di 3 cifre utilizzato da Nielsen per identificare la Designated Market Area (DMA) associata agli eventi di visualizzazione descritti nella riga di dati.
city
La città stimata associata alle metriche nella riga del report. I dati per questa dimensione sono disponibili per le date a partire dal 1° gennaio 2022.
continent (solo filtro)
Un codice regione statistica delle Nazioni Unite (ONU). L'API supporta i seguenti valori:
Valore Descrizione
002 Africa
019 Americhe (Nord America, America Latina, Sud America e Caraibi)
142 Asia
150 Europa
009 Oceania
Questa dimensione può essere utilizzata solo per filtrare i dati. Per utilizzare questa dimensione, imposta il valore del parametro filters su continent==REGION_CODE, specificando un valore REGION_CODE dalla tabella.
subContinent (solo filtro)
Un codice regione statistica delle Nazioni Unite che identifica una sottoregione geografica. La Divisione statistica delle Nazioni Unite elenca le sottoregioni e i paesi associati a ciascuna regione.

Questa dimensione può essere utilizzata solo per filtrare i dati. Per utilizzare questa dimensione, imposta il valore del parametro filters su subContinent==REGION_CODE, specificando un valore REGION_CODE dall'elenco delle Nazioni Unite.

Esempi

Le seguenti richieste di esempio utilizzano dimensioni o filtri geografici:

  • Esempi di canali

    • Statistiche di base: conteggi delle visualizzazioni specifici per paese (e altro) per un canale
    • Area geografica
      • Metriche sul tempo di visualizzazione specifiche per paese per i video di un canale
      • Metriche specifiche per paese relative alle annotazioni per i video di un canale
      • Metriche specifiche per provincia per gli stati degli Stati Uniti e Washington D.C.
      • Metriche sul tempo di visualizzazione specifiche per paese per le playlist di un canale
      • Top 10: le playlist più create negli Stati Uniti
    • Luogo di visualizzazione: conteggi delle visualizzazioni e tempo di visualizzazione giornalieri da diversi luoghi di visualizzazione
    • Sorgente di traffico: visualizzazioni e tempo di visualizzazione provenienti da diverse sorgenti di traffico in un paese
    • Dati demografici: dati demografici degli spettatori in California (fascia d'età e genere)
    • Video principali
      • Top 10: i video più visti in un paese specifico
      • Top 10: i video più visti in Europa

  • Esempi di proprietari dei contenuti

    • Statistiche di base: numero di visualizzazioni specifiche per paese (e altro) per tutti i video caricati autonomamente
    • Area geografica
      • Metriche sul tempo di visualizzazione specifiche per paese per i contenuti caricati autonomamente
      • Metriche delle annotazioni specifiche per paese per i contenuti caricati autonomamente
      • Metriche specifiche per provincia per gli stati degli Stati Uniti e Washington D.C.
      • Metriche sul tempo di visualizzazione specifiche per paese per le playlist di un proprietario dei contenuti
      • Top 10: le playlist più create negli Stati Uniti
    • Luogo di visualizzazione: conteggi delle visualizzazioni e tempo di visualizzazione giornalieri da diversi luoghi di visualizzazione
    • Dati demografici: dati demografici degli spettatori in California (fascia d'età e genere)
    • Video principali: i 10 video più guardati in Europa per un proprietario dei contenuti
    • Entrate/Rendimento degli annunci: metriche sul rendimento degli annunci e sulle entrate specifiche per paese

Periodi di tempo

Queste dimensioni indicano che un report deve aggregare i dati in base a un periodo di tempo, ad esempio un giorno, una settimana o un mese. I parametri della richiesta startDate e endDate specificano il periodo di tempo per il quale il report include i dati. Tieni presente che il report restituisce i dati fino all'ultimo giorno per il quale tutte le metriche specificate nella richiesta sono disponibili al momento dell'esecuzione della query. Nei report, le date sono elencate nel formato YYYY-MM-DD.

Importante:tutte le date si riferiscono al periodo di tempo che inizia alle ore 00:00 (fuso orario del Pacifico, UTC-7 o UTC-8) e termina alle ore 23:59 (fuso orario del Pacifico) del giorno, del mese e dell'anno specificati. Di conseguenza, le date in cui gli orologi vengono spostati in avanti per l'ora legale rappresentano un periodo di 23 ore, mentre le date in cui gli orologi vengono spostati indietro rappresentano un periodo di 25 ore.

La dimensione Mese si riferisce al periodo di tempo che inizia alle ore 00:00 (fuso orario del Pacifico, UTC-7 o UTC-8) del primo giorno del mese e dell'anno specificati.

Giorno (dimensione principale)
Quando utilizzi questa dimensione, i dati nel report vengono aggregati su base giornaliera e ogni riga contiene i dati di un giorno. Puoi utilizzare altre dimensioni per suddividere ulteriormente i dati. Ad esempio, un report sulle sorgenti di traffico può aggregare le statistiche di visualizzazione giornaliere in base al modo in cui gli utenti raggiungono i tuoi video. This is a core dimension and is subject to the Deprecation Policy.
mese (dimensione principale)
I dati nel report sono aggregati per mese di calendario. Come per i report giornalieri, puoi utilizzare altri filtri per segmentare ulteriormente i dati. Nel report, le date sono elencate nel formato YYYY-MM.

Nota:se la query API utilizza la dimensione month, i parametri start-date e end-date devono essere impostati sul primo giorno del mese. This is a core dimension and is subject to the Deprecation Policy.

Esempi

Le seguenti richieste di esempio utilizzano dimensioni o filtri temporali:

  • Esempi di canali

    • Basato sulla durata
      • Metriche sul tempo di visualizzazione giornaliero per i video di un canale
      • Metriche giornaliere delle annotazioni per i video di un canale
      • Visualizzazioni giornaliere delle playlist per un canale
    • Luogo di visualizzazione: conteggi delle visualizzazioni e tempo di visualizzazione giornalieri da diversi luoghi di visualizzazione
    • Sorgente di traffico: conteggi giornalieri delle visualizzazioni e tempo di visualizzazione provenienti da diverse sorgenti di traffico
    • Dispositivo/Sistema operativo
      • Metriche giornaliere sul tipo di dispositivo per il sistema operativo Android
      • Metriche giornaliere del sistema operativo per i dispositivi mobili
      • Metriche giornaliere relative al sistema operativo e al tipo di dispositivo

  • Esempi di proprietari dei contenuti

    • Basato sulla durata
      • Metriche sul tempo di visualizzazione giornaliero per i contenuti caricati personalmente
      • Metriche delle annotazioni per i contenuti rivendicati
      • Visualizzazioni giornaliere delle playlist per un proprietario dei contenuti
    • Luogo di visualizzazione: conteggi delle visualizzazioni e tempo di visualizzazione giornalieri da diversi luoghi di visualizzazione
    • Sorgente di traffico: conteggi giornalieri delle visualizzazioni e tempo di visualizzazione provenienti da diverse sorgenti di traffico
    • Dispositivo/Sistema operativo
      • Metriche giornaliere sul tipo di dispositivo per i video rivendicati
      • Metriche giornaliere del sistema operativo per i video rivendicati visualizzati su dispositivi mobili
      • Metriche giornaliere relative al sistema operativo e al tipo di dispositivo
    • Entrate/Rendimento degli annunci: metriche giornaliere su entrate e rendimento degli annunci

Luoghi di visualizzazione

Queste dimensioni forniscono informazioni sulla pagina o sull'applicazione in cui si è verificata l'attività dell'utente.

insightPlaybackLocationType
I dati nel report vengono aggregati in base al tipo di pagina o applicazione in cui si sono verificati i playback dei video. I valori possibili per questa dimensione sono:

  • BROWSE: i dati descrivono le visualizzazioni avvenute sulla home page o sulla schermata Home di YouTube, nel feed Iscrizioni dell'utente o in un'altra funzionalità di navigazione di YouTube.

  • CHANNEL: i dati descrivono le visualizzazioni che si sono verificate in una pagina del canale.

  • EMBEDDED: i dati descrivono le visualizzazioni avvenute su un altro sito web o un'altra applicazione in cui il video è stato incorporato utilizzando un incorporamento <iframe> o <object>.

  • EXTERNAL_APP: i dati descrivono le visualizzazioni avvenute in un'applicazione di terze parti in cui il video è stato riprodotto utilizzando un metodo diverso da un incorporamento <iframe> o <object>. Ad esempio, le riproduzioni nelle applicazioni che utilizzano l'API YouTube Android Player verranno classificate in base a questo valore.

  • MOBILE: i dati descrivono le visualizzazioni avvenute sul sito web mobile di YouTube o su client API di YouTube approvati, inclusi i dispositivi mobili.

    A partire dal 10 settembre 2013, le riproduzioni non vengono più classificate come riproduzioni MOBILE nei report di YouTube Analytics. Il valore potrebbe rimanere nei report perché i dati legacy rientrano ancora in questa categoria. Tuttavia, dopo questa data, le riproduzioni su dispositivi mobili vengono classificate come riproduzioni WATCH, EMBEDDED o EXTERNAL_APP, a seconda del tipo di applicazione in cui si verificano.

  • SEARCH: i dati descrivono le visualizzazioni avvenute direttamente nella pagina dei risultati di ricerca di YouTube.

  • WATCH: i dati descrivono le visualizzazioni avvenute nella pagina di visualizzazione di YouTube del video o in un'applicazione YouTube ufficiale, ad esempio l'app YouTube per Android.

  • YT_OTHER: i dati descrivono le visualizzazioni che non sono classificate in altro modo.

insightPlaybackLocationDetail
I dati vengono aggregati in base alla pagina in cui si trova il player. Tieni presente che questo report è supportato solo per le visualizzazioni avvenute nei player incorporati e identifica i player incorporati che hanno generato il maggior numero di visualizzazioni per un video specifico. Pertanto, fornisce una visualizzazione più granulare rispetto al report sul luogo di visualizzazione, identificando gli URL o le applicazioni associati ai principali player incorporati.

Esempi

Le seguenti richieste di esempio utilizzano le dimensioni del luogo di visualizzazione:

  • Esempi di canali

    • Luogo di visualizzazione
      • Visualizzazioni e tempo di visualizzazione da diverse posizioni di riproduzione
      • Conteggi delle visualizzazioni e tempo di visualizzazione giornalieri da diverse posizioni di riproduzione
      • I primi 10: i siti di terze parti che generano il maggior numero di visualizzazioni per un video incorporato
      • Conteggi delle visualizzazioni e tempo di visualizzazione delle playlist da diverse posizioni di riproduzione
      • Conteggi delle visualizzazioni e tempo di visualizzazione giornalieri delle playlist da diverse posizioni di riproduzione

  • Esempi di proprietari dei contenuti