Dimensions

Este documento define as dimensões compatíveis com a API YouTube Analytics. Essa API permite consultas segmentadas em tempo real para gerar relatórios personalizados do YouTube Analytics.

As dimensões são critérios comuns usados para agregar dados, como a data em que a atividade do usuário ocorreu ou o país em que os usuários estavam.

Cada relatório de consulta identifica as dimensões compatíveis. Por exemplo, ao recuperar a atividade do usuário por tempo, você escolhe o período para o qual os dados serão informados: dia ou mês. Em qualquer relatório, cada linha de dados tem uma combinação única de valores de dimensão.

Para recuperar um relatório de consulta, chame o método reports.query da API YouTube Analytics. Na sua solicitação, use o parâmetro dimensions para especificar as dimensões que o YouTube vai usar para calcular os valores das métricas nos relatórios.

Dimensões principais

Embora a API YouTube Analytics esteja sujeita à Política de Descontinuação definida nos Termos de Serviço, as dimensões não essenciais (e as métricas não essenciais) não estão sujeitas à política. Nas definições desta página, qualquer dimensão que seja principal é explicitamente identificada como tal.

A lista a seguir identifica as principais dimensões da API.

Para mais informações, consulte a lista de APIs do YouTube sujeitas à política de descontinuação.

Filtros

Todos os relatórios de consulta são compatíveis com filtros. Os filtros identificam os valores de dimensão que precisam estar presentes no conjunto de dados recuperado. Assim, eles limitam uma resposta da API para incluir apenas dados que correspondam a um valor ou conjunto de valores específico. Por exemplo, em vez de recuperar métricas de atividade do usuário para todos os países, use um filtro para recuperar dados apenas de um país específico.

Em uma solicitação para recuperar um relatório de consulta, o parâmetro de solicitação opcional filters especifica os valores de dimensão para os quais você quer filtrar dados. Por exemplo, para recuperar métricas de atividade do usuário na Europa, defina o valor do parâmetro filters como continent==150.

Importante: as solicitações de API para recuperar relatórios do proprietário do conteúdo precisam filtrar os dados usando uma das dimensões da entidade de relatórios ou uma combinação compatível das dimensões claimedStatus e uploaderType.

Dimensões

As seções a seguir definem as dimensões usadas nos relatórios de consulta da API YouTube Analytics. A menos que indicado de outra forma, essas dimensões são usadas nos relatórios de canal e de proprietário do conteúdo. As dimensões que só podem ser usadas como filtros também são identificadas.

Recursos

Essas dimensões correspondem aos recursos que os canais e os proprietários de conteúdo gerenciam no YouTube:

Observação: a API permite especificar vários valores para as dimensões video, playlist e channel quando elas são usadas como filtros. Para isso, defina o valor do parâmetro filters como uma lista separada por vírgulas dos IDs de vídeos, playlists ou canais que você quer filtrar na resposta da API. O valor do parâmetro pode especificar até 500 IDs.

video (dimensão principal)
O ID de um vídeo do YouTube. Na API YouTube Data, esse é o valor da propriedade id de um recurso video. This is a core dimension and is subject to the Deprecation Policy.
playlist
O ID de uma playlist do YouTube. Na API YouTube Data, esse é o valor da propriedade id de um recurso playlist.
channel (dimensão principal) (usada apenas em relatórios do proprietário do conteúdo)
O ID de um canal do YouTube. Na API YouTube Data, esse é o valor da propriedade id de um recurso channel. This is a core dimension and is subject to the Deprecation Policy.

A dimensão channel é usada com frequência nos relatórios do proprietário do conteúdo porque eles costumam agregar dados de vários canais.
group (somente filtro)
O ID de um grupo do YouTube Analytics. É possível recuperar esse valor usando o método groups.list da API YouTube Analytics. Quando você usa o filtro group, a resposta da API contém dados de todos os vídeos, playlists ou canais desse grupo.

Exemplos

Os exemplos de solicitações a seguir usam dimensões ou filtros de entidade de relatório:

  • Exemplos de canais

    • Estatísticas básicas
      • 10 mais – Vídeos mais assistidos para um canal
      • Top 10: taxas de cliques de anotações para os vídeos mais assistidos de um canal
      • Estatísticas de uma playlist específica
      • Top 10: playlists mais assistidas de um canal
    • Geográfica
      • 10 mais – Vídeos mais visualizados em um país específico
      • Top 10: vídeos mais assistidos na Europa

  • Exemplos de proprietários de conteúdo

    • Estatísticas básicas
      • Top 10: vídeos mais assistidos de um proprietário do conteúdo
      • Os 10 vídeos mais assistidos de um proprietário de conteúdo
      • Os 10 vídeos mais assistidos do canal de um proprietário de conteúdo
      • Top 10: taxas de cliques de anotações para os vídeos mais assistidos de um canal
      • Top 10: playlists mais assistidas de um proprietário de conteúdo
    • Geográfica
      • Top 10: vídeos mais assistidos na Europa para um proprietário de conteúdo
      • Top 10 – Playlists mais iniciadas nos Estados Unidos

Áreas geográficas

Essas dimensões identificam uma região geográfica associada à atividade do usuário, à performance do anúncio ou às métricas de receita estimada.

country (dimensão principal)
O país associado às métricas na linha do relatório. O valor da dimensão é um código de país ISO-3166-1 de duas letras, como US, CN (China) ou FR (França). O código de país ZZ é usado para informar métricas em que o YouTube não conseguiu identificar o país associado. This is a core dimension and is subject to the Deprecation Policy.
province
O estado ou território dos EUA associado às métricas na linha do relatório. O valor da dimensão é um código ISO 3166-2 que identifica um estado dos EUA ou o Distrito de Columbia, como US-MI (Michigan) ou US-TX (Texas). O código de província US-ZZ é usado para informar métricas em que o YouTube não conseguiu identificar o estado dos EUA associado. Quando uma solicitação de API inclui province no valor do parâmetro dimensions, ela também precisa restringir os dados aos Estados Unidos incluindo country==US no valor do parâmetro filters.

Observação: essa dimensão não é compatível com valores ISO 3166-2 que identificam áreas periféricas dos EUA, já que esses territórios também têm os próprios códigos de país ISO 3166-1. Ele também não é compatível com subdivisões de países que não sejam os Estados Unidos.

dma
O identificador de três dígitos que a Nielsen usa para identificar a Área designada do mercado (DMA) associada aos eventos de visualização descritos na linha de dados.
city
A cidade estimada associada às métricas na linha do relatório. Os dados dessa dimensão estão disponíveis para datas a partir de 1º de janeiro de 2022.
continent (somente filtro)
Um código de região estatística das Nações Unidas (ONU). A API aceita os seguintes valores:
Valor Descrição
002 África
019 Américas (América do Norte, América Latina, América do Sul e Caribe)
142 Ásia
150 Europa
009 Oceania
Essa dimensão só pode ser usada para filtrar dados. Para usar essa dimensão, defina o valor do parâmetro filters como continent==REGION_CODE, especificando um valor REGION_CODE da tabela.
subContinent (somente filtro)
Um código de região estatística da ONU que identifica uma sub-região geográfica. A Divisão de Estatísticas das Nações Unidas lista as sub-regiões e os países associados a cada região.

Essa dimensão só pode ser usada para filtrar dados. Para usar essa dimensão, defina o valor do parâmetro filters como subContinent==REGION_CODE, especificando um valor REGION_CODE da lista da ONU.

Exemplos

Os exemplos de solicitações a seguir usam dimensões ou filtros geográficos:

  • Exemplos de canais

    • Estatísticas básicas: contagem de visualizações específicas de um país (e mais) para um canal
    • Geográfica
      • Métricas de tempo de exibição específicas de um país para vídeos de um canal
      • Métricas de anotação específicas de um país para vídeos de um canal
      • Métricas específicas de províncias para estados dos EUA e Washington D.C.
      • Métricas de tempo de exibição por país para as playlists de um canal
      • Top 10: playlists mais iniciadas nos Estados Unidos
    • Local da visualização: contagem de visualizações diárias e tempo de exibição de diferentes locais de visualização.
    • Origem do tráfego: contagem de visualizações e tempo de exibição de diferentes origens de tráfego em um país.
    • Informações demográficas: informações demográficas dos espectadores na Califórnia (faixa etária e gênero)
    • Vídeos mais acessados
      • 10 mais – Vídeos mais visualizados em um país específico
      • Top 10: vídeos mais assistidos na Europa

  • Exemplos de proprietários de conteúdo

    • Estatísticas básicas: contagem de visualizações por país (e mais) para todos os vídeos enviados por você
    • Geográfica
      • Métricas do tempo de exibição específico de um país para o conteúdo enviado automaticamente
      • Métricas de anotação específicas de um país para o conteúdo enviado automaticamente
      • Métricas específicas de províncias para estados dos EUA e Washington D.C.
      • Métricas de tempo de exibição específicas de um país para as playlists de um proprietário de conteúdo.
      • Top 10 – Playlists mais iniciadas nos Estados Unidos
    • Local da visualização: contagem de visualizações diárias e tempo de exibição de diferentes locais de visualização.
    • Informações demográficas: informações demográficas dos espectadores na Califórnia (faixa etária e gênero)
    • Vídeos mais acessados: os 10 vídeos mais assistidos na Europa de um proprietário de conteúdo.
    • Receita/performance do anúncio: métricas de receita e performance do anúncio específicas do país.

Períodos

Essas dimensões indicam que um relatório deve agregar dados com base em um período, como um dia, uma semana ou um mês. Os parâmetros de solicitação startDate e endDate especificam o período dos dados incluídos no relatório. O relatório retorna dados até o último dia em que todas as métricas especificadas na solicitação estão disponíveis no momento em que a consulta é feita. Nos relatórios, as datas são listadas no formato YYYY-MM-DD.

Importante: todas as datas se referem ao período que começa à meia-noite do horário do Pacífico (UTC-7 ou UTC-8) e termina às 23h59 do horário do Pacífico no dia, mês e ano especificados. Como resultado, as datas em que os relógios são adiantados para o horário de verão representam um período de 23 horas, e as datas em que os relógios são atrasados representam um período de 25 horas.

A dimensão mês se refere ao período que começa às 12h, horário do Pacífico (UTC-7 ou UTC-8), no primeiro dia do mês e ano especificados.

day (dimensão principal)
Quando você usa essa dimensão, os dados no relatório são agregados diariamente, e cada linha contém dados de um dia. Você pode usar outras dimensões para detalhar ainda mais os dados. Por exemplo, um relatório de origem do tráfego pode agregar estatísticas de visualização diárias com base na maneira como os usuários chegam aos seus vídeos. This is a core dimension and is subject to the Deprecation Policy.
month (dimensão principal)
Os dados no relatório são agregados por mês. Assim como acontece com relatórios diários, é possível usar outros filtros para segmentar os dados ainda mais. No relatório, as datas são listadas no formato YYYY-MM.

Observação: se a consulta de API usar a dimensão month, os parâmetros start-date e end-date precisarão ser definidos como o primeiro dia do mês. This is a core dimension and is subject to the Deprecation Policy.

Exemplos

As seguintes solicitações de amostra usam dimensões ou filtros temporais:

  • Exemplos de canais

    • De acordo com o horário
      • Métricas diárias de tempo de exibição para vídeos de um canal
      • Métricas de anotação diárias para vídeos de um canal
      • Visualizações diárias de playlists de um canal
    • Local da visualização: contagem de visualizações diárias e tempo de exibição de diferentes locais de visualização.
    • Origem do tráfego: contagens diárias de visualizações e tempo de exibição de diferentes origens de tráfego.
    • Dispositivo/SO
      • Métricas diárias do tipo de dispositivo para o sistema operacional Android
      • Métricas diárias do sistema operacional para dispositivos móveis
      • Métricas diárias do sistema operacional e do tipo de dispositivo

  • Exemplos de proprietários de conteúdo

    • De acordo com o horário
      • Métricas diárias do tempo de exibição para o conteúdo enviado automaticamente
      • Métricas de anotação para o conteúdo reivindicado
      • Visualizações diárias de playlists de um proprietário de conteúdo
    • Local da visualização: contagem de visualizações diárias e tempo de exibição de diferentes locais de visualização.
    • Origem do tráfego: contagens diárias de visualizações e tempo de exibição de diferentes origens de tráfego.
    • Dispositivo/SO
      • Métricas diárias do tipo de dispositivo para vídeos reivindicados
      • Métricas diárias do sistema operacional para vídeos reivindicados visualizados em dispositivos móveis
      • Métricas diárias do sistema operacional e do tipo de dispositivo
    • Receita/performance do anúncio: métricas diárias de receita e performance do anúncio.

Locais de reprodução

Essas dimensões fornecem insights sobre a página ou o aplicativo em que a atividade do usuário ocorreu.

insightPlaybackLocationType
Os dados no relatório são agregados com base no tipo de página ou aplicativo em que as exibições de vídeo ocorreram. Os valores possíveis para essa dimensão são:

  • BROWSE: os dados descrevem as visualizações que ocorreram na página inicial do YouTube ou na tela inicial, no feed de inscrições do usuário ou em outro recurso de navegação do YouTube.

  • CHANNEL: os dados descrevem as visualizações que ocorreram em uma página do canal.

  • EMBEDDED: os dados descrevem as visualizações que ocorreram em outro site ou aplicativo em que o vídeo foi incorporado usando uma incorporação <iframe> ou <object>.

  • EXTERNAL_APP: os dados descrevem as visualizações que ocorreram em um aplicativo de terceiros em que o vídeo foi reproduzido usando um método diferente de uma incorporação <iframe> ou <object>. Por exemplo, as reproduções em aplicativos que usam a API YouTube Android Player seriam categorizadas com esse valor.

  • IMMERSIVE_LIVE_FEED: os dados descrevem as visualizações que ocorreram no feed vertical ao vivo.

  • MOBILE: os dados descrevem as visualizações que ocorreram no site móvel do YouTube ou em clientes de API do YouTube aprovados, incluindo dispositivos móveis.

    Desde 10 de setembro de 2013, as visualizações não são mais categorizadas como visualizações de MOBILE nos relatórios do YouTube Analytics. O valor pode permanecer nos relatórios, já que os dados legados ainda se enquadram nessa categoria. No entanto, após essa data, as visualizações em dispositivos móveis serão classificadas como WATCH, EMBEDDED ou EXTERNAL_APP, dependendo do tipo de aplicativo em que elas ocorrerem.

  • SEARCH: os dados descrevem as visualizações que ocorreram diretamente na página de resultados da Pesquisa do YouTube.

  • SHORTS_FEED: os dados descrevem as visualizações que ocorreram no Feed dos Shorts.

  • WATCH: os dados descrevem as visualizações que ocorreram na página de exibição do vídeo no YouTube ou em um aplicativo oficial do YouTube, como o app YouTube para Android.

  • YT_OTHER: os dados descrevem visualizações que não estão classificadas de outra forma.

insightPlaybackLocationDetail
Os dados são agregados com base na página em que o player está localizado. Esse relatório é suportado apenas por visualizações que ocorreram em players integrados e identifica os players integrados que geraram o maior número de visualizações de um vídeo especificado. Dessa forma, ele fornece uma visualização mais refinada do que o relatório de local de reprodução identificando os URLs ou os aplicativos associados aos principais players integrados.

Exemplos

Os seguintes exemplos de solicitação usam dimensões de local de reprodução:

  • Exemplos de canais

    • Local de reprodução
      • Contagens de exibições e tempo de exibição de diferentes locais de reprodução
      • Contagem de visualizações diárias e tempo de exibição de diferentes locais de reprodução
      • 10 mais – Sites de terceiros que geram o maior número de visualizações para um vídeo incorporado
      • Contagem de visualizações e tempo de exibição da playlist em diferentes locais de reprodução
      • Contagem diária de visualizações e tempo de exibição da playlist em diferentes locais de reprodução

  • Exemplos de proprietários de conteúdo

    • Local de reprodução
      • Contagens de exibições e tempo de exibição de diferentes locais de reprodução
      • Contagem de visualizações diárias e tempo de exibição de diferentes locais de reprodução
      • 10 mais – Sites de terceiros que geram o maior número de visualizações para um vídeo incorporado
      • Contagem de visualizações e tempo de exibição da playlist em diferentes locais de reprodução
      • Contagem diária de visualizações e tempo de exibição da playlist em diferentes locais de reprodução

Detalhes da reprodução

creatorContentType
Essa dimensão identifica o tipo de conteúdo associado às métricas de atividade do usuário na linha de dados. Os dados dessa dimensão estão disponíveis para datas a partir de 1º de janeiro de 2019.

A tabela a seguir lista os valores da dimensão:
Valor Descrição
LIVE_STREAM O conteúdo assistido era uma transmissão ao vivo do YouTube.
SHORTS O conteúdo assistido era um Short do YouTube.
STORY O conteúdo assistido era uma História do YouTube.
VIDEO_ON_DEMAND O conteúdo visualizado era um vídeo do YouTube que não se enquadra em um dos outros valores de dimensão.
UNSPECIFIED O tipo de conteúdo visualizado é desconhecido.
liveOrOnDemand
Essa dimensão indica se as métricas de atividade do usuário na linha de dados estão associadas às visualizações de uma transmissão ao vivo. Os dados dessa dimensão estão disponíveis para datas a partir de 1º de abril de 2014.

A tabela a seguir lista os valores da dimensão:
Valor Descrição
LIVE Os dados da linha descrevem a atividade do usuário que ocorreu durante uma transmissão ao vivo.
ON_DEMAND Os dados da linha descrevem a atividade do usuário que não ocorreu durante uma transmissão ao vivo.
subscribedStatus
Essa dimensão indica se as métricas de atividade do usuário na linha de dados estão associadas a espectadores que se inscreveram no canal do vídeo ou da playlist. Os valores possíveis são SUBSCRIBED e UNSUBSCRIBED.

O valor da dimensão é preciso no momento em que a atividade do usuário ocorre. Por exemplo, imagine que um usuário não inscrito em um canal assista a um vídeo dele, se inscreva e assista a outro vídeo, tudo no mesmo dia. O relatório do canal indica que uma visualização tem um valor subscribedStatus de SUBSCRIBED, e outra tem um valor subscribedStatus de UNSUBSCRIBED.
youtubeProduct
Essa dimensão identifica o serviço do YouTube em que a atividade do usuário ocorreu. Os dados dessa dimensão estão disponíveis desde 18 de julho de 2015.

A tabela a seguir lista os valores da dimensão:
Valor Descrição
CORE A atividade do usuário que não ocorreu em um dos aplicativos especializados do YouTube (YouTube Gaming, YouTube Kids ou YouTube Music). Exceção: a atividade do usuário que ocorreu no YouTube Music antes de 1º de março de 2021 está incluída em CORE.
GAMING A atividade do usuário ocorreu no YouTube Gaming.
KIDS A atividade do usuário ocorreu no YouTube Kids.
MUSIC A atividade do usuário ocorreu no YouTube Music em 1º de março de 2021 ou depois dessa data. Os dados anteriores a 1º de março de 2021 estão incluídos em CORE. Os dados em tempo real não são gravados.
UNKNOWN A atividade do usuário ocorreu antes de 18 de julho de 2015.

Origens de tráfego

insightTrafficSourceType
Os dados no relatório são agregados com base no tipo de origem, que descreve como os usuários chegaram ao vídeo. Os valores possíveis para essa dimensão são:
  • ADVERTISING: o espectador foi direcionado ao vídeo por um anúncio. Se você filtrar com base nessa origem de tráfego, o campo insightTrafficSourceDetail vai identificar o tipo de anúncio.
  • ANNOTATION: os espectadores chegaram ao vídeo clicando em uma anotação em outro vídeo.
  • CAMPAIGN_CARD: visualizações originadas de vídeos reivindicados enviados por usuários que o proprietário do conteúdo usou para promover o conteúdo visualizado. Essa origem de tráfego só é compatível com relatórios de proprietários de conteúdo.
  • END_SCREEN: as visualizações foram originadas na tela final de outro vídeo.
  • EXT_URL: as visualizações do vídeo foram originadas de um link em outro site. Se você filtrar com base nessa origem de tráfego, o campo insightTrafficSourceDetail vai identificar a página da Web. Essa origem de tráfego inclui as referências dos resultados da pesquisa do Google.
  • HASHTAGS: visualizações originadas de páginas de hashtag de VOD ou de páginas temáticas de hashtag dos Shorts.
  • LIVE_REDIRECT: as visualizações do vídeo foram encaminhadas por Redirecionamentos em tempo real.
  • NO_LINK_EMBEDDED: o vídeo foi incorporado a outro site quando foi assistido.
  • NO_LINK_OTHER: o YouTube não identificou um referenciador para o tráfego. Esta categoria engloba o tráfego direto a um vídeo, o tráfego de aplicativos móveis.
  • NOTIFICATION: as visualizações do vídeo foram originadas de um e-mail ou de uma notificação do YouTube.
  • PLAYLIST: as visualizações ocorreram enquanto o vídeo estava sendo reproduzido como parte de uma playlist. Inclui o tráfego que vem da página da playlist.
  • PRODUCT_PAGE: as visualizações do vídeo foram encaminhadas de uma página do produto.
  • PROMOTED: as visualizações do vídeo foram geradas por uma promoção não paga do YouTube, como a página "Vídeos em destaque".
  • RELATED_VIDEO: as visualizações do vídeo foram originadas de uma lista de vídeos relacionados em outra página de exibição. Se você filtrar com base nessa origem de tráfego, o campo insightTrafficSourceDetail vai especificar o ID do vídeo.
  • SHORTS: o espectador foi direcionado ao deslizar verticalmente do vídeo anterior na experiência de visualização dos Shorts.
  • SOUND_PAGE: visualizações originadas de páginas temáticas de áudio dos Shorts.
  • SUBSCRIBER: as visualizações do vídeo foram originadas de feeds na página inicial do YouTube ou de recursos de inscrição do YouTube. Se você filtrar com base nessa origem de tráfego, o campo insightTrafficSourceDetail vai especificar os itens do feed da página inicial ou outra página de onde as visualizações foram encaminhadas.
  • YT_CHANNEL: as visualizações do vídeo ocorreram na página de um canal. Se você filtrar com base nessa origem de tráfego, o campo insightTrafficSourceDetail vai especificar o ID do canal.
  • YT_OTHER_PAGE: as visualizações do vídeo foram originadas de um link que não era um resultado da pesquisa ou um link de vídeo relacionado que apareceu em uma página do YouTube. Se você filtrar com base nessa origem de tráfego, o campo insightTrafficSourceDetail vai identificar a página.
  • YT_SEARCH: as visualizações do vídeo foram originadas dos resultados da Pesquisa do YouTube. Se você filtrar com base nessa origem de tráfego, o campo insightTrafficSourceDetail vai especificar o termo de pesquisa.
  • VIDEO_REMIXES: as visualizações do vídeo foram originadas do link do vídeo remixado no player dos Shorts. Se você filtrar com base nessa origem de tráfego, o campo insightTrafficSourceDetail vai especificar o vídeo de onde o espectador foi encaminhado.
  • WATCH_WITH: as visualizações do vídeo foram indicadas por uma transmissão de comentários do criador de conteúdo / "Assista com". Se você filtrar com base nessa origem de tráfego, o campo insightTrafficSourceDetail vai especificar o vídeo de onde o espectador foi encaminhado.
insightTrafficSourceDetail
Os dados no relatório são agregados com base nas referências que geraram mais visualizações para um vídeo e um tipo de origem de tráfego específicos. A lista a seguir identifica as origens de tráfego para as quais esse relatório está disponível. Para cada origem de tráfego, a lista identifica as informações fornecidas pela dimensão insightTrafficSourceDetail.
  • ADVERTISING: o tipo de anúncio que levou às visualizações. Os valores possíveis são:
    • Anúncio de engajamento clique para assistir
    • Anúncio de engajamento
    • Anúncios de pesquisa do Google
    • Anúncio em vídeo na página inicial
    • In-stream pulável reservado
    • TrueView in-search e in-display
    • TrueView in-stream
    • Publicidade no YouTube sem classificação
    • Mural de vídeos
  • CAMPAIGN_CARD: o vídeo reivindicado que levou os espectadores ao vídeo identificado no relatório.
  • END_SCREEN: o vídeo que levou os espectadores ao conteúdo identificado no relatório.
  • EXT_URL: o site que direcionou os espectadores para o vídeo.
  • HASHTAGS: a hashtag que levou às visualizações.
  • NOTIFICATION: o e-mail ou a notificação que encaminhou o tráfego.
  • RELATED_VIDEO: o vídeo relacionado que levou os espectadores ao vídeo abordado no relatório.
  • SOUND_PAGE: o vídeo que gerou as visualizações.
  • SUBSCRIBER: o item do feed da página inicial ou o recurso de inscrição do YouTube que levou os espectadores ao vídeo abordado no relatório. Os valores válidos são:
    • activity: visualizações de itens nos feeds de inscrição da página inicial que resultaram de atividades não relacionadas a envios e canais sociais, incluindo marcações "Gostei", favoritos, postagens de boletins e adições à playlist.
    • blogged: visualizações de itens nos feeds de inscrição da página inicial que resultaram de links dos principais blogs.
    • mychannel: visualizações de itens em outros feeds listados na página inicial, como "Gostei", "Histórico de exibição" e "Assistir mais tarde".
    • podcasts: visualizações originadas de itens na página de destino de podcasts.
    • sdig: visualizações originadas de e-mails de atualização de inscrição.
    • uploaded: visualizações dos itens uploaded nos feeds de inscrição da página inicial.
    • /: outras visualizações que vêm da página inicial do YouTube.
    • /my_subscriptions: visualizações originadas das páginas Minhas inscrições dos usuários no YouTube.
  • YT_CHANNEL: a página do canal em que os espectadores assistiram o vídeo.
  • YT_OTHER_PAGE: a página do YouTube que direcionou os espectadores ao vídeo.
  • YT_SEARCH: o termo de pesquisa que levou os espectadores ao vídeo.
  • VIDEO_REMIXES: o vídeo que gerou as visualizações.
  • WATCH_WITH: o vídeo que gerou as visualizações.

Exemplos

Os seguintes exemplos de solicitação usam dimensões de origem de tráfego:

  • Exemplos de canais

    • Origem do tráfego
      • Contagens de exibições e tempo de exibição de diferentes origens de tráfego em um país
      • Contagem de visualizações diárias e tempo de exibição de diferentes origens de tráfego
      • 10 mais – Termos de pesquisa do YouTube que geram mais tráfego para um vídeo
      • Os 10 principais termos de Pesquisa Google que geram mais tráfego para um vídeo.
      • Contagem de visualizações e tempo de exibição de playlists de diferentes origens de tráfego em um país
      • Contagem de visualizações diárias e tempo de exibição de playlists de diferentes origens de tráfego

  • Exemplos de proprietários de conteúdo

    • Origem do tráfego
      • Contagens de exibições e tempo de exibição de diferentes origens de tráfego
      • Contagem de visualizações diárias e tempo de exibição de diferentes origens de tráfego
      • 10 mais – Termos de pesquisa do YouTube que geram mais tráfego para um vídeo
      • Os 10 principais termos de Pesquisa Google que geram mais tráfego para um vídeo.
      • Contagem de visualizações e tempo de exibição de playlists de diferentes origens de tráfego em um país
      • Contagem de visualizações diárias e tempo de exibição de playlists de diferentes origens de tráfego

Dispositivos

deviceType
Essa dimensão identifica o formato físico do dispositivo em que a visualização ocorreu. A lista a seguir identifica os tipos de dispositivo para os quais a API retorna dados. Também é possível usar a dimensão deviceType como um filtro para restringir um relatório de sistema operacional para que ele contenha apenas dados de um tipo específico de dispositivo.
  • DESKTOP
  • GAME_CONSOLE
  • MOBILE
  • TABLET
  • TV
  • AUTOMOTIVE
  • WEARABLE
  • UNKNOWN_PLATFORM
operatingSystem
Essa dimensão identifica o sistema de software do dispositivo em que a visualização ocorreu. A lista a seguir identifica os sistemas operacionais para os quais a API retorna dados. Também é possível usar operatingSystem como um filtro para restringir um relatório de tipo de dispositivo para que ele contenha apenas dados de um sistema operacional específico.
  • ANDROID
  • BADA
  • BLACKBERRY
  • CHROMECAST
  • DOCOMO
  • FIREFOX
  • HIPTOP
  • IOS
  • KAIOS
  • LINUX
  • MACINTOSH
  • MEEGO
  • NINTENDO_3DS
  • OTHER
  • PLAYSTATION
  • PLAYSTATION_VITA
  • REALMEDIA
  • SMART_TV
  • SYMBIAN
  • TIZEN
  • VIDAA
  • WEBOS
  • WII
  • WINDOWS
  • WINDOWS_MOBILE
  • XBOX

Exemplos

Os seguintes exemplos de solicitação usam dimensões do dispositivo:

  • Exemplos de canais

    • Dispositivo/SO
      • Métricas diárias do tipo de dispositivo para o sistema operacional Android
      • Métricas diárias do sistema operacional para dispositivos móveis
      • Métricas diárias do sistema operacional e do tipo de dispositivo
      • Métricas diárias de tipo de dispositivo para visualizações de playlists no sistema operacional Android
      • Métricas diárias do sistema operacional para visualizações de playlists em dispositivos móveis

  • Exemplos de proprietários de conteúdo

    • Dispositivo/SO
      • Métricas diárias do tipo de dispositivo para vídeos reivindicados
      • Métricas diárias do sistema operacional para vídeos reivindicados visualizados em dispositivos móveis
      • Métricas diárias do sistema operacional e do tipo de dispositivo
      • Métricas diárias de tipo de dispositivo para visualizações de playlists no sistema operacional Android
      • Métricas diárias do sistema operacional para visualizações de playlists em dispositivos móveis

Informações demográficas

As dimensões demográficas ajudam a entender a faixa etária e a distribuição de gênero do seu público. A Central de Ajuda do YouTube contém mais informações sobre dados demográficos nos relatórios do YouTube Analytics.

ageGroup (dimensão principal)
Essa dimensão identifica a faixa etária dos usuários conectados associados aos dados do relatório e inclui usuários que o YouTube estima que tenham menos de 18 anos. A API usa as seguintes faixas etárias:
  • age13-17
  • age18-24
  • age25-34
  • age35-44
  • age45-54
  • age55-64
  • age65-
This is a core dimension and is subject to the Deprecation Policy.
gender (dimensão principal)
Essa dimensão identifica o gênero dos usuários conectados associados aos dados do relatório. Os valores válidos são female, male e user_specified. This is a core dimension and is subject to the Deprecation Policy.

Exemplos

Os seguintes exemplos de solicitação usam dimensões demográficas:

  • Exemplos de canais

    • Informações demográficas
      • Informações demográficas dos espectadores na Califórnia (faixa etária e gênero)
      • Informações demográficas dos espectadores da playlist na Califórnia (faixa etária e gênero)

  • Exemplos de proprietários de conteúdo

    • Informações demográficas
      • Informações demográficas dos espectadores na Califórnia (faixa etária e gênero)
      • Informações demográficas dos espectadores da playlist na Califórnia (faixa etária e gênero)

Engajamento e compartilhamento de conteúdo

sharingService (dimensão principal)
Essa dimensão identifica o serviço usado para compartilhar vídeos. Os vídeos podem ser compartilhados no YouTube (ou pelo player do YouTube), utilizando o botão "Compartilhar". This is a core dimension and is subject to the Deprecation Policy.

A tabela a seguir lista os valores de dimensão válidos:
Serviço de compartilhamento Valor da API
Allo ALLO
Ameba AMEBA
E-mail do Android ANDROID_EMAIL
Android Messenger ANDROID_MESSENGER
Mensagens do Android ANDROID_MMS
Caixa de diálogo de compartilhamento do sistema Android ANDROID_SYSTEM_SHARE_DIALOG
BlackBerry Messenger BBM
Receber uma reação BLIND_REACT
Blogger BLOGGER
Copiar para a área de transferência COPY_PASTE
Cyworld CYWORLD
Digg DIGG
Caixa de diálogo de atividade direta do sistema DIRECT_SYSTEM_ACTIVITY_DIALOG
Discord DISCORD
QR code exibido DISPLAYED_QR_CODE
Dropbox DROPBOX
Incorporar EMBED
E-mail MAIL
Facebook FACEBOOK
Facebook Lite FACEBOOK_LITE
Facebook Messenger FACEBOOK_MESSENGER
Páginas do Facebook FACEBOOK_PAGES
Compartilhar no grupo do Facebook FACEBOOK_SHARE_TO_GROUP
Stories do Facebook FACEBOOK_STORIES
Fotka FOTKA
Gmail GMAIL
goo GOO
App do Google GOOGLE_APP
Google Chat GOOGLE_CHAT
Google Chrome GOOGLE_CHROME
Google Inbox INBOX
Google Keep GOOGLE_KEEP
Google+ GOOGLEPLUS
Go SMS GO_SMS
GroupMe GROUPME
Hangouts HANGOUTS
hi5 HI5
Mensagem de texto da HTC HTC_MMS
IMO IMO
Instagram INSTAGRAM
Stories do Instagram INSTAGRAM_STORIES
Link do convite (Android) INVITE_LINK_ANDROID
Link do convite (iOS) INVITE_LINK_IOS
Convidar colaboradores para a playlist INVITE_PLAYLIST_COLLABORATORS
Caixa de diálogo de atividade do sistema iOS IOS_SYSTEM_ACTIVITY_DIALOG
KAKAO Story KAKAO_STORY
Kakao (Kakao Talk) KAKAO
Mensagens do KaiOS KAIOS_MESSAGES
Kik KIK
E-mail da LGE LGE_EMAIL
Linha LINE
LinkedIn LINKEDIN
LiveJournal LIVEJOURNAL
Copiar/colar do Maps MAPS_COPY_PASTE
Compartilhamento ao vivo do Meet MEET_LIVE_SHARING
menéame MENEAME
mixi MIXI
Mensagens da Motorola MOTOROLA_MESSAGING
Myspace MYSPACE
Naver NAVER
Compartilhar por proximidade NEARBY_SHARE
NUjij NUJIJ
Odnoklassniki (Одноклассники) ODNOKLASSNIKI
Outro OTHER
Pinterest PINTEREST
Quick Share QUICK_SHARE
Quick Share (Samsung) QUICK_SHARE_SAMSUNG
Rakuten (楽天市場) RAKUTEN
reddit REDDIT
Remix REMIX
Samsung Messages SAMSUNG_MESSAGES
Samsung Notes SAMSUNG_NOTES
Salvar nas fotos do dispositivo SAVE_TO_DEVICE_PHOTOS
Compartilhar sem anúncios SHARE_AD_FREE
Compartilhar com a câmera do Snapchat SHARE_TO_SNAPCHAT_CAMERA
Compartilhar com crianças SHARE_WITH_KIDS
Skype SKYPE
Skyrock SKYBLOG
Snapchat SNAPCHAT
Conversas da Sony SONY_CONVERSATIONS
StumbleUpon STUMBLEUPON
Telegram TELEGRAM
Mensagem de texto TEXT_MESSAGE
Tuenti TUENTI
tumblr. TUMBLR
Twitter TWITTER
Desconhecido UNKNOWN
Verizon Messages VERIZON_MMS
Viber VIBER
VKontakte (ВКонтакте) VKONTAKTE
Caixa de diálogo de atividade do sistema da Web WEB_SYSTEM_ACTIVITY_DIALOG
WeChat WECHAT
Weibo WEIBO
WhatsApp WHATS_APP
WhatsApp Business WHATS_APP_BUSINESS
Wykop WYKOP
Yahoo! Japan YAHOO
Post na Comunidade do YouTube YOUTUBE_COMMUNITY_POST
Repost na Comunidade do YouTube YOUTUBE_COMMUNITY_REPOST
YouTube Gaming YOUTUBE_GAMING
YouTube Kids YOUTUBE_KIDS
YouTube Mango YOUTUBE_MANGO
YouTube Music YOUTUBE_MUSIC
Prévia do compartilhamento no Snapchat de conteúdo do YouTube Music YTM_SHARE_TO_SNAPCHAT_PREVIEW
Tela verde do YouTube Shorts YOUTUBE_SHORTS_GREEN_SCREEN
YouTube TV YOUTUBE_TV
Assistir com amigos no YouTube YOUTUBE_WATCH_WITH_FRIENDS

Consulte os documentos de ajuda para mais informações.

Exemplos

Os seguintes exemplos de solicitação usam dimensões sociais:

  • Exemplos de canais

    • Social: métricas de compartilhamento, agregadas pelo serviço em que os vídeos foram compartilhados.

  • Exemplos de proprietários de conteúdo

    • Social: métricas de compartilhamento, agregadas pelo serviço em que os vídeos foram compartilhados.

Retenção de público

elapsedVideoTimeRatio
Essa dimensão especifica a proporção da parte decorrida do vídeo em relação à duração total. As dimensões e métricas de retenção são usadas para medir a retenção de público ao longo do tempo, e a dimensão elapsedVideoTimeRatio é a medição de tempo. Por exemplo, um valor de 0.4 indica que os dados do relatório correspondente mostram dados de retenção depois que 40% do vídeo foi assistido.

A API retorna 100 pontos de dados para cada vídeo com valores de proporção que variam de 0.01 a 1.0. Os momentos em que os dados são medidos durante as reproduções de vídeo são igualmente espaçados para cada vídeo. Isso significa que, para um vídeo de dois minutos, o intervalo entre os pontos de dados é de 1,2 segundo. No entanto, para um vídeo de duas horas, o intervalo entre os pontos de dados é de 72 segundos. O valor da dimensão indica o fim exclusivo do intervalo.
audienceType (somente filtro)
O valor da dimensão identifica o tipo de tráfego associado aos dados do relatório. Os valores aceitos são ORGANIC, AD_INSTREAM e AD_INDISPLAY. Consulte a Central de Ajuda do YouTube para ver explicações sobre esses tipos de origem de tráfego.

Os dados do filtro audienceType estão disponíveis desde 25 de setembro de 2013. A API não retorna dados para consultas que usam o filtro para tentar recuperar dados de datas anteriores. As consultas que não usam o filtro funcionam para qualquer data após 1º de julho de 2008.

Exemplos

Os exemplos de solicitações a seguir usam dimensões de retenção de público:

Transmissão ao vivo

livestreamPosition
Essa dimensão especifica um minuto específico durante uma transmissão de vídeo ao vivo. As métricas do relatório indicam quantos usuários estavam assistindo a transmissão ao vivo naquele momento.

Cancelamentos de assinaturas

membershipsCancellationSurveyReason
O número de pesquisas respondidas por usuários do YouTube que cancelaram o Clube do Canal especificado durante o período do relatório. A tabela a seguir lista os valores de dimensão válidos:
Valor da API Explicação
UNKNOWN O usuário não concluiu a pesquisa.
DISLIKE_PERKS O usuário não gostou dos benefícios da assinatura.
PERKS_NOT_DELIVERED O usuário disse que os benefícios de assinatura prometidos não foram entregues.
CANNOT_ACCESS_PERKS O usuário não conseguiu acessar os benefícios.
NO_LONGER_INTERESTED O usuário não tem mais interesse em ser membro do canal.
FEEL_UNAPPRECIATED O usuário não se sentiu valorizado como membro do canal.
FINANCIAL_REASONS O usuário cancelou por motivos financeiros.
JOIN_LIMITED_TIME O usuário só queria apoiar o canal por um tempo limitado.
OTHER O usuário tinha outro motivo para cancelar.

Desempenho do anúncio

adType
A dimensão adType é usada em relatórios de performance dos anúncios e agrega as métricas solicitadas com base nos tipos de anúncios veiculados durante as exibições de vídeo. A lista a seguir explica os possíveis valores de dimensão. Consulte a Central de Ajuda do YouTube para mais informações sobre os formatos de publicidade no YouTube.

  • auctionBumperInstream: anúncios em vídeo não puláveis de até 6 segundos, veiculados por leilão, que precisam ser assistidos antes do vídeo.

  • auctionDisplay: um anúncio gráfico ou de rich media que aparece como uma sobreposição na parte de baixo do player de vídeo, como um bloco de anúncios de 300 x 250 na página de exibição do vídeo ou como uma combinação de ambos. Quando a sobreposição é executada, ela é automaticamente fechada após a exibição por determinado período. O usuário também pode fechá-la. Se uma sobreposição e um banner forem exibidos juntos, cada anúncio é contado como uma impressão separada.

  • auctionInstream: anúncios em vídeo não puláveis que são veiculados antes, durante ou depois do vídeo principal.

  • auctionTrueviewInslate: o espectador escolhe um dos vários anúncios em vídeo de uma seleção de opções mostradas antes de um vídeo. See the TrueView documentation for more information.

  • auctionTrueviewInstream: anúncios em vídeo puláveis que são veiculados antes ou durante o vídeo principal. Consulte a documentação do TrueView para mais informações.

  • auctionUnknown: um anúncio que foi comprado pelo leilão do Google Ads, mas que não foi classificado em um dos outros tipos de anúncio.

  • reservedBumperInstream: anúncios em vídeo não puláveis de até 6 segundos, vendidos por reserva, que precisam ser assistidos antes do vídeo.

  • reservedClickToPlay: um anúncio em vídeo que o usuário precisa clicar para iniciar a reprodução. Uma impressão de anúncio é registrada em qualquer momento em que o bloco de anúncio click-to-play for exibido, independentemente de o usuário iniciar a reprodução. Eles são vendidos de forma reservada.

  • reservedDisplay: um anúncio gráfico ou de rich media que aparece como uma sobreposição na parte de baixo do player de vídeo, como um bloco de anúncios de 300 x 250 na página de exibição do vídeo ou como uma combinação de ambos. Quando a sobreposição é executada, ela é automaticamente fechada após a exibição por determinado período. O usuário também pode fechá-la. Se uma sobreposição e um banner forem exibidos juntos, cada anúncio é contado como uma impressão separada.

  • reservedInstream: anúncios em vídeo não puláveis inseridos antes, durante ou depois do vídeo principal.

  • reservedInstreamSelect

  • reservedMasthead: um anúncio grande, que pode incluir elementos gráficos e de vídeo, que aparece na página inicial.

  • reservedUnknown: um anúncio vendido por reserva que não pôde ser classificado em um dos outros tipos de anúncio.

  • unknown: o YouTube não conseguiu classificar esse tipo de anúncio.

Exemplos

Os relatórios de exemplo a seguir recuperam métricas de performance do anúncio ou receita:

  • Exemplos de canais

    • Receita/anúncios
      • Métricas de receita do canal e performance dos anúncios
      • Métricas diárias de receita e performance do anúncio
      • Métricas de receita e performance de anúncios específicas do país
      • Os 10 vídeos com a maior receita
      • Métricas de desempenho de anúncios para diferentes tipos de anúncios

  • Exemplos de proprietários de conteúdo

    • Receita/anúncios
      • Métricas de receita e performance do anúncio para conteúdo reivindicado
      • Métricas diárias de receita e performance do anúncio
      • Métricas de receita e performance de anúncios específicas do país
      • Os 10 vídeos com a maior receita
      • Métricas de desempenho de anúncios para diferentes tipos de anúncios

Dimensões do proprietário do conteúdo

As dimensões a seguir são suportadas somente para relatórios do proprietário do conteúdo.

Importante: as solicitações de API para recuperar relatórios do proprietário do conteúdo precisam filtrar os dados usando uma das seguintes dimensões:
  • video
  • channel
  • Uma combinação aceita das dimensões claimedStatus e uploaderType, conforme definido abaixo.
claimedStatus (usado apenas em relatórios de proprietários do conteúdo)
Essa dimensão permite indicar que uma resposta da API deve conter apenas métricas de conteúdo reivindicado. O único valor válido para essa dimensão é claimed. Se o parâmetro filters restringir a consulta a claimedStatus==claimed, a API vai recuperar apenas dados de conteúdo reivindicado. A tabela na definição da dimensão uploaderType fornece mais detalhes sobre como usar essa dimensão.
uploaderType (dimensão principal) (usada apenas em relatórios do proprietário do conteúdo)
Essa dimensão permite indicar se uma resposta da API deve conter métricas para o conteúdo enviado pelo proprietário do conteúdo especificado e/ou por terceiros, como vídeos enviados por usuários. Os valores válidos são self e thirdParty. Essa é uma dimensão principal e está sujeita à Política de descontinuação.

A tabela a seguir mostra as combinações compatíveis com as dimensões claimedStatus e uploaderType, que são usadas no parâmetro filters:

Valor de claimedStatus Valor de uploaderType Descrição
[Não definido] self Recupera dados do YouTube Analytics para o conteúdo reivindicado e não reivindicado enviado pelo proprietário do conteúdo.
reivindicados [Não definido] Recupera dados para o conteúdo reivindicado enviado pelo proprietário do conteúdo ou por um terceiro.
reivindicados self Recupera dados para o conteúdo reivindicado enviado pelo proprietário do conteúdo.
reivindicados thirdParty Recupera dados para o conteúdo reivindicado enviado por um terceiro.

Exemplos

Muitas das solicitações de API de exemplo para relatórios de proprietário do conteúdo usam uma combinação compatível das dimensões claimedStatus e uploaderType para filtrar dados.