Introduction

Neste documento, explicamos as semelhanças e diferenças entre a API YouTube Analytics e a API YouTube Reporting fornecem acesso aos dados do YouTube Analytics. O objetivo do documento é ajudar você a escolher a API certa para seu aplicativo.

Ambas as APIs permitem que os desenvolvedores recuperem dados do YouTube Analytics. Além disso, as duas APIs oferecem suporte para proprietários de canais e de conteúdo do YouTube, cada um com acesso a um conjunto específico de relatórios:

  • Relatórios de canal contêm métricas de atividade do usuário para um canal especificado.

  • Relatórios do proprietário do conteúdo agregam métricas para todos os canais vinculados a um proprietário do conteúdo do YouTube especificado. Por exemplo, uma gravadora pode recuperar um relatório que contenha estatísticas combinadas para os canais do YouTube de todos os artistas da gravadora. Alguns relatórios do proprietário do conteúdo contêm métricas de atividade do usuário, enquanto outros contêm métricas relacionadas à receita e ao desempenho do anúncio.

A API Reporting também permite que alguns proprietários de conteúdo acessem relatórios de receita de publicidade gerenciados pelo sistema. Os dados dos relatórios gerenciados pelo sistema só podem ser recuperados com a API Reporting.

Todas as solicitações da API YouTube Analytics e YouTube Reporting precisam ser autorizadas pelo canal ou proprietário do conteúdo que tem os dados solicitados.

Denunciar conteúdo

Os relatórios recuperados pelas APIs contêm dois tipos de dados:

  • Dimensões são critérios comuns usados ​​para dados agregados, como a data em que ocorreu a atividade do usuário ou o país em que os usuários estavam localizad.

    Em um relatório, cada linha de dados tem uma combinação única de valores de dimensão. Assim, a combinação de valores de dimensão de cada linha funciona como a chave primária para a linha.

  • As métricas são medidas individuais de atividade do usuário, desempenho de anúncios ou receita estimada. As métricas de atividade do usuário incluem coisas como contagens e classificações de visualização de vídeos (marcações "Gostei" e "Não gostei").

Escolha a API certa para seu aplicativo

API do YouTube Analytics
A API YouTube Analytics aceita consultas segmentadas em tempo real para gerar relatórios personalizados do YouTube Analytics. A API fornece parâmetros de filtragem e classificação. Assim, o aplicativo de chamada não precisa oferecer suporte nativo a essas funções.

Cada solicitação de API especifica o período para o qual os dados serão retornados. A API também permite que você recupere conjuntos de dados semanais e mensais. Assim, o aplicativo de chamada não precisa armazenar conjuntos de dados recuperados ou agregar estatísticas em diferentes períodos.
API Reporting do YouTube
A API YouTube Reporting recupera relatórios em massa que contêm dados do YouTube Analytics para um proprietário de conteúdo ou canal. Ele foi projetado para aplicativos que podem importar grandes conjuntos de dados e que fornecem ferramentas para filtrar, classificar e minerar esses dados.

Cada relatório contém um conjunto predefinido de campos. Os desenvolvedores usam a API para programar jobs de geração de relatórios, e cada um deles identifica um relatório que o YouTube deve gerar. Então, o YouTube gera um relatório diário que pode ser baixado de forma assíncrona. Cada relatório contém dados de um período exclusivo de 24 horas.

Além disso, o YouTube gera automaticamente um conjunto de relatórios gerenciados pelo sistema para os proprietários do conteúdo que têm acesso aos relatórios correspondentes no YouTube Creator Studio. Esses relatórios oferecem acesso programático a dados de receita de publicidade.

Relatórios compatíveis

A tabela a seguir identifica os diferentes tipos de relatórios que você pode recuperar usando as APIs. As consultas segmentadas estão disponíveis pela API YouTube Analytics, e os relatórios em massa estão disponíveis na API YouTube Reporting.

Os dados disponíveis em uma API podem não estar disponíveis na outra. Por exemplo, a API YouTube Analytics permite recuperar métricas de atividade do usuário semanalmente ou mensalmente, mas a API YouTube Reporting exige que você agregue esses dados por conta própria. Por outro lado, a API YouTube Reporting é compatível com relatórios de recursos para proprietários do conteúdo, mas esses dados não estão disponíveis na API YouTube Analytics.

Tipos de relatório
Relatórios de vídeo Compatível com canais (consulta ou em massa) e proprietários de conteúdo (consulta ou em massa).

Os relatórios de vídeo mostram estatísticas de todas as atividades do usuário relacionadas aos vídeos de um canal ou aos vídeos de um proprietário do conteúdo. Por exemplo, esses relatórios contêm o número de visualizações que seus vídeos receberam. Na API YouTube Analytics, alguns relatórios de vídeo do proprietário do conteúdo também incluem métricas de receita estimada e desempenho de anúncios.
Relatórios de playlists Compatível com canais (consulta ou em massa) e proprietários de conteúdo (consulta ou em massa).

Os relatórios de playlists apresentam estatísticas relacionadas especificamente às exibições de vídeos que ocorrem no contexto de uma playlist. A API YouTube Reporting oferece suporte a relatórios de retenção de público para playlists, mas a API YouTube Analytics não oferece suporte a relatórios semelhantes.
Relatórios de desempenho do anúncio Compatível com proprietários de conteúdo (consulta ou em massa).

Os relatórios de desempenho de anúncios apresentam métricas com base em impressões para anúncios exibidos durante reproduções de vídeo. Essas métricas representam cada impressão de anúncio, e cada reprodução de vídeo pode gerar várias impressões.
Relatórios de receita estimada Compatível com proprietários de conteúdo (em massa).

Os relatórios de receita estimada mostram a receita estimada total dos vídeos de origens de publicidade vendidas pelo Google e de outras origens. Esses relatórios também contêm algumas métricas de desempenho de anúncios. Os relatórios gerenciados pelo sistema contêm a receita real.
Relatórios de recursos Compatível com proprietários de conteúdo (em massa).

Os relatórios de recursos apresentam métricas de atividade do usuário relacionadas a vídeos vinculados aos recursos de um proprietário do conteúdo. Um vídeo será incluído no relatório do proprietário de um conteúdo se o proprietário do conteúdo tiver reivindicado esse vídeo como uma correspondência de um dos recursos do proprietário. O vídeo pode ter sido enviado pelo proprietário do conteúdo ou por outro usuário do YouTube.
Relatórios gerenciados pelo sistema Compatível com proprietários de conteúdo que têm acesso aos relatórios correspondentes no menu "Relatórios" do YouTube Creator Studio.

Os relatórios gerenciados pelo sistema mostram os dados da receita real gerada por recursos e vídeos. Um relatório adicional lista os vídeos reivindicados e os recursos correspondentes. No momento, nem todos os relatórios do Creator Studio estão disponíveis na API.

Observação:o YouTube gera automaticamente relatórios gerenciados pelo sistema para os proprietários do conteúdo que têm acesso aos relatórios correspondentes no YouTube Studio. Como resultado, o processo de recuperação desses relatórios é diferente dos outros tipos de relatórios nessa lista. Consulte a documentação dos relatórios gerenciados pelo sistema para mais informações.

Principais diferenças

A tabela a seguir destaca diferenças importantes entre o YouTube Analytics e as APIs Reporting.

Recurso API do YouTube Analytics API Reporting do YouTube
Processo para recuperar dados Cada solicitação de API especifica dimensões e métricas a serem retornadas, bem como o período em que os dados serão retornados. Os aplicativos programam jobs de geração de relatórios. Para cada tarefa, o YouTube gera relatórios diários que podem ser baixados de forma assíncrona.
Períodos Alguns relatórios da API especificam a data em que a atividade do usuário ocorreu. Alguns desses relatórios oferecem suporte a dimensões para agregar métricas de atividade do usuário por mês. Todos os relatórios da API especificam o dia em que a atividade do usuário ocorreu. Os aplicativos que usam a API podem implementar recursos para agregar dados em intervalos periódicos.
Filtrar dados É possível filtrar os relatórios para incluir somente as linhas em que uma dimensão tem um valor específico. A API também oferece suporte a algumas dimensões, como continente e subContinent, que são usadas somente como filtros. A API suporta downloads em massa de conjuntos de dados completos. Ela não oferece suporte para filtragem nem mostra dados para dimensões somente para filtro. O aplicativo cliente armazena os dados baixados e implementa seus próprios recursos para filtrar os dados.
Classificação Os relatórios podem ser classificados com base nos valores de métricas retornados. Alguns relatórios suportam apenas um número limitado de resultados. Por exemplo, o relatório que lista os vídeos mais visualizados de um canal retorna no máximo 200 linhas. Essa API suporta downloads em massa de conjuntos de dados completos. Os aplicativos clientes podem implementar os próprios recursos para classificar os dados baixados.
Enumerações Os relatórios da API contêm valores de texto, como "ANDROID" ou "CHANNEL", para identificar valores de dimensão enumerados. Os relatórios da API contêm números inteiros que podem ser mapeados para valores de texto.
Cota O servidor de API avalia cada consulta para determinar o custo da cota. A seção uso da cota explica a metodologia em mais detalhes. O uso da cota não é um problema porque os dados são recuperados uma vez e, em seguida, filtrados, classificados e consultados no aplicativo.
Relatórios exclusivos
  • Atividade do usuário relacionada às legendas
  • Dados de retenção de público para playlists
  • Relatórios de receita estimada para proprietários do conteúdo (há dois relatórios diferentes)
  • Relatórios de recursos para proprietários do conteúdo (11 relatórios diferentes estão disponíveis)
Dimensões exclusivas grupo (dimensão somente filtro)
continent (dimensão somente filtro)
subContinent (dimensão somente filtro)
mês
isCurated==1 (dimensão somente filtro)
viewsPerPlaylistStart
averageTimeInPlaylist
annotation_id
annotation_type
asset_id
card_id
card_type
live_or_on_demand
subscribed_status
subtitle_language
Métricas exclusivas uniques
relativeRetentionPerformance
viewsPerPlaylistStart
averageTimeInPlaylist
card_click_rate
card_clicks
card_impressions
card_teaser_click_rate
card_teaser_clicks
card_teaser_impressions
estimated_partner_adsense_revenue
estimated_partner_doubleclick_save2playlist_save2{16_partner_doubleclick_save}{16_partner_doubleclick_save} removida16}

playlist_saves_addedplaylist_saves_removed

Diferenças de nomenclatura entre APIs

Atualmente, as duas APIs usam convenções de nomenclatura diferentes para identificar dimensões e métricas. No momento, os nomes da API YouTube Analytics usam camelCase, enquanto os nomes da API YouTube Reporting usam nomes delimitados por sublinhados.

As tabelas a seguir identificam os diferentes nomes que as duas APIs usam para identificar as mesmas métricas e dimensões. Em alguns casos, a diferença entre os dois nomes é maior do que a que você teria após converter um nome de camelCase para sublinhados. Por exemplo, a dimensão video na API YouTube Analytics é chamada de video_id na API YouTube Reporting.

Dimensões

Nome da API YouTube Analytics Nome da API YouTube Reporting
adType ad_type
ageGroup age_group
recurso asset_id
audienceType audience_retention_type
channel channel_id
claimedStatus claimed_status
contentOwner content_owner_id
country country_code
dia date
deviceType device_type
elapsedVideoTimeRatio elapsed_video_time_percentage
gender [gênero] gender [gênero]
insightPlaybackLocationDetail playback_location_detail
insightPlaybackLocationType playback_location_type
insightTrafficSourceDetail traffic_source_detail
insightTrafficSourceType traffic_source_type
liveOrOnDemand live_or_on_demand
operatingSystem operating_system
playlist playlist_id
province province_code
sharingService sharing_service
subscribedStatus subscribed_status
subtitleLanguage subtitle_language
uploaderType uploader_type
vídeo video_id

Métricas

Nome da API YouTube Analytics Nome da API YouTube Reporting
adEarnings estimated_partner_ad_revenue
annotationImpressions annotation_impressions
annotationClickableImpressions annotation_clickable_impressions
annotationClicks annotation_clicks
annotationClickThroughRate annotation_click_through_rate
annotationClosableImpressions annotation_closable_impressions
annotationCloses annotation_closes
annotationCloseRate annotation_close_rate
audienceWatchRatio audience_retention_percentage
averageViewDuration average_view_duration_seconds
averageViewPercentage average_view_duration_percentage
cardClickRate card_click_rate
cardClicks card_clicks
cardImpressions card_impressions
cardTeaserClickRate card_teaser_click_rate
cardTeaserClicks card_teaser_clicks
cardTeaserImpressions card_teaser_impressions
comments comments
não gostei não gostei
ganhos estimated_partner_revenue
estimatedMinutesWatched watch_time_minutes
estimatedPartnerAdSenseRevenue estimated_partner_adsense_revenue
estimatedPartnerDoubleClickRevenue estimated_partner_doubleclick_revenue
grossRevenue estimated_youtube_ad_revenue
impressionBasedCpm estimated_cpm
impressões ad_impressions
marcações "Gostei" marcações "Gostei"
monetizedPlaybacks estimated_monetized_playbacks
playbackBasedCpm estimated_playback_based_cpm
playlistStarts playlist_starts
savesAdded playlist_saves_added
savesRemoved playlist_saves_removed
compartilhamentos compartilhamentos
subscribersGained subscribers_gained
subscribersLost subscribers_lost
videosAddedToPlaylists videos_added_to_playlists
videosRemovedFromPlaylists videos_removed_from_playlist
viewerPercentage views_percentage
visualizações visualizações