Este documento explica as semelhanças e diferenças nas formas como a API YouTube Analytics e a API YouTube Reporting fornecem acesso aos dados do YouTube Analytics. Assim, você pode escolher a API certa para seu aplicativo.
As duas APIs permitem recuperar dados do YouTube Analytics. Além disso, as duas APIs são compatíveis com proprietários de canais e de conteúdo do YouTube, que podem acessar 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 acessar um relatório com estatísticas combinadas dos canais do YouTube de todos os artistas dela. Alguns relatórios de proprietários de conteúdo têm métricas de atividade do usuário, enquanto outros têm métricas relacionadas à receita e à performance de anúncios.
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 nos relatórios gerenciados pelo sistema só podem ser recuperados com a API Reporting.
Todas as solicitações de API YouTube Analytics e YouTube Reporting precisam ser autorizadas pelo proprietário do canal ou do conteúdo que detém os dados solicitados.
Conteúdo do relatório
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 dela.
-
As métricas são medições individuais da atividade do usuário, do desempenho do anúncio ou da receita estimada. As métricas de atividade do usuário incluem contagens de visualizações de vídeo e classificações (gostei e não gostei).
Escolher a API certa para seu aplicativo
- API do YouTube Analytics
- A API YouTube Analytics permite consultas segmentadas em tempo real para gerar relatórios personalizados do YouTube Analytics. A API fornece parâmetros de filtragem e classificação, para que o aplicativo de chamada não precise oferecer suporte nativo a essas funções.
Cada solicitação de API especifica o período em que os dados serão retornados. Com a API, também é possível recuperar conjuntos de dados semanais e mensais. Assim, o aplicativo de chamada não precisa armazenar conjuntos de dados recuperados nem agregar estatísticas em intervalos de datas. - API Reporting do YouTube
- A API YouTube Reporting recupera relatórios em massa com dados do YouTube Analytics para um proprietário de conteúdo ou canal. Ela foi projetada para aplicativos que podem importar grandes conjuntos de dados e que oferecem ferramentas para filtrar, classificar e extrair esses dados.
Cada relatório contém um conjunto predefinido de campos. Você usa a API para programar trabalhos de geração de relatórios, cada um deles identificando um relatório que o YouTube precisa gerar. Em seguida, 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 proprietários de conteúdo que têm acesso aos relatórios correspondentes no YouTube Creator Studio. Esses relatórios oferecem acesso programático aos dados de receita de publicidade.
Relatórios compatíveis
A tabela a seguir identifica os diferentes tipos de relatórios que podem ser extraídos usando as APIs. As consultas segmentadas estão disponíveis usando a API YouTube Analytics, e os relatórios em massa estão disponíveis usando a 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 oferece suporte a relatórios de recursos para proprietários de 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 (query ou bulk) e proprietários de conteúdo (query ou bulk). Os relatórios de vídeo fornecem estatísticas de toda a atividade do usuário relacionada aos vídeos de um canal ou de um proprietário de 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 (query ou bulk) e proprietários de conteúdo (query ou bulk). Os relatórios de playlists fornecem estatísticas relacionadas especificamente às visualizações de vídeo que ocorrem no contexto de uma playlist. A API YouTube Reporting é compatível com relatórios de retenção de público-alvo para playlists, mas a API YouTube Analytics não oferece um relatório semelhante. |
| Relatórios de desempenho do anúncio | Disponível para proprietários de conteúdo (consulta ou em massa). Os relatórios de performance de anúncios fornecem métricas com base em impressões para anúncios veiculados durante as reproduções de vídeo. Essas métricas consideram cada impressão de anúncio, e cada reprodução de vídeo pode gerar várias impressões. |
| Relatórios de receita estimada | Disponível para proprietários de conteúdo (em massa). Os relatórios de receita estimada mostram a receita total estimada dos vídeos de fontes de publicidade vendidas pelo Google e de fontes que não são de publicidade. Esses relatórios também contêm algumas métricas de performance de anúncios. Os relatórios gerenciados pelo sistema contêm a receita real. |
| Relatórios de recursos | Disponível para proprietários de conteúdo (em massa). Os relatórios de recursos fornecem métricas de atividade do usuário relacionadas a vídeos vinculados aos recursos de um proprietário do conteúdo. Um vídeo é incluído no relatório de um proprietário de conteúdo se ele reivindicou o vídeo como correspondente a um dos recursos dele. 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 | Disponível para proprietários de conteúdo que têm acesso aos relatórios correspondentes no menu "Relatórios" do YouTube Studio. Os relatórios gerenciados pelo sistema fornecem dados da receita real obtida por recursos e vídeos. Outro relatório lista os vídeos reivindicados e os recursos correspondentes. Nem todos os relatórios do YouTube Studio estão disponíveis na API. Observação:o YouTube gera automaticamente relatórios gerenciados pelo sistema para proprietários de conteúdo que têm acesso aos relatórios correspondentes no YouTube Studio. Por isso, o processo para recuperar esses relatórios é diferente dos outros tipos na lista. Consulte a documentação sobre relatórios gerenciados pelo sistema para mais informações. |
principais diferenças
A tabela a seguir destaca diferenças importantes entre as APIs YouTube Analytics e Reporting.
| Recurso | API do YouTube Analytics | API Reporting do YouTube |
|---|---|---|
| Processo para extrair dados | Cada solicitação de API especifica as dimensões e métricas que serão 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 job, 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 de 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 | Você pode filtrar os relatórios para incluir apenas 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 apenas como filtros. | A API é compatível com downloads em massa de conjuntos de dados completos. Ele não oferece suporte à filtragem nem retorna dados para dimensões somente de filtro. O aplicativo cliente armazena os dados baixados e implementa recursos próprios para filtrar os dados. |
| Classificação | Os relatórios podem ser classificados com base nos valores de métrica retornados. Alguns relatórios só aceitam um número limitado de resultados. Por exemplo, o relatório que lista os vídeos mais assistidos de um canal retorna no máximo 200 linhas. | Essa API é compatível com o download em massa de conjuntos de dados completos. Os aplicativos cliente podem implementar recursos próprios 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 da 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 depois filtrados, classificados e consultados no aplicativo. |
| Relatórios de Unique Reach |
|
|
| Dimensões exclusivas | group (dimensão somente para filtro) continent (dimensão somente para filtro) subContinent (dimensão somente para filtro) month 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_revenue playlist_saves_added playlist_saves_removed |
Diferenças de nomenclatura entre as APIs
As duas APIs usam convenções de nomenclatura diferentes para identificar dimensões e métricas. Os nomes das APIs do YouTube Analytics usam camelCase, como adType. Os nomes da API YouTube Reporting estão em letras minúsculas e usam sublinhados, como ad_type.
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 o que você teria depois de 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.