Comparativos de mercado do YouTube

Importante: esse recurso está disponível apenas para contas em uma lista de permissões. Entre em contato com seu representante do Google se precisar de acesso a esse recurso.

O BenchmarksService permite que anunciantes e agências comparem a performance dos anúncios do YouTube com os comparativos de mercado. Com esse serviço, é possível avaliar a performance das suas campanhas em relação aos segmentos do setor ou a todos os anunciantes em categorias específicas de produtos e serviços.

Principais recursos

Com o BenchmarksService, é possível:

• Comparar a performance: avalie as métricas de taxa média de um cliente (como CPM, CPV, CTR e visibilidade) em relação às médias agregadas do setor.
• Analisar a participação de mercado: entenda a presença relativa de um cliente no mercado com a participação de voz (impressões relativas) e a participação de gastos.
• Avaliar a posição competitiva: meça a posição competitiva de um cliente usando métricas de percentil que classificam a performance em dimensões importantes em níveis competitivos (como Líder de mercado ou Concorrente).
• Segmentar por tempo: agrupe as métricas de comparativo de mercado por granularidades temporais semanais, mensais ou trimestrais.
• Descubra as dimensões de comparativo de mercado compatíveis: consulte os períodos, as localizações geográficas, os produtos de publicidade e as fontes de comparativo de mercado (segmentos do setor ou categorias de produtos e serviços) disponíveis.

Observação : é necessário fornecer um ID de cliente nas suas solicitações. Um ID de cliente de conta de administrador não retorna métricas de cliente porque as contas de administrador não veiculam campanhas publicitárias diretamente.

Métodos de descoberta

Antes de gerar métricas de comparativo de mercado, use os métodos de descoberta para recuperar os parâmetros válidos e os critérios de escopo das suas solicitações.

Listar datas de disponibilidade

O método ListBenchmarksAvailableDates retorna os períodos históricos que dão suporte aos dados de comparativo de mercado em um ListBenchmarksAvailableDatesResponse.

A resposta fornece dois períodos distintos:

• supported_dates: o período geral em que as métricas de comparativo de mercado são compatíveis (inclusive). As solicitações de comparativo de mercado podem consultar datas dentro desse período.
• supported_dates_for_all_metrics (na v25 e versões mais recentes): um subconjunto de supported_dates que oferece suporte ao conjunto completo de métricas de comparativo de mercado. Algumas métricas, especificamente as de participação do cliente (share_of_voice e share_of_spend) e as de taxa média da origem do comparativo de mercado, estão disponíveis apenas nesse período devido à disponibilidade limitada de dados. Essas métricas serão omitidas da resposta se o date_range solicitado não estiver completamente dentro de supported_dates_for_all_metrics.

Listar locais

O método ListBenchmarksLocations retorna a lista de localizações geográficas (como países) que aceitam dados de comparativo de mercado.

Cada BenchmarksLocation na resposta inclui:

• location_name: o nome exclusivo do local em inglês (por exemplo, "United States").
• location_type: o tipo de local correspondente ao target_type na API Google Ads (por exemplo, "Country").
• location_info: um objeto LocationInfo que contém a constante de segmentação geográfica (como geo_target_constant: "geoTargetConstants/2840").

Listar produtos

O método ListBenchmarksProducts retorna a lista de produtos e objetivos de marketing disponíveis para comparação.

Cada entrada BenchmarksProductMetadata inclui:

• product_name: o nome do produto fácil de usar.
• product_code: a string do identificador exclusivo do produto, usada ao criar um ProductFilter.
• marketing_objective: o objetivo de marketing associado (BenchmarksMarketingObjective):
  • AWARENESS: campanhas criadas para aumentar o reconhecimento da marca ou do produto.
  • CONSIDERATION: campanhas criadas para incentivar clientes em potencial a considerar a marca ou os produtos.
  • ACTION: campanhas criadas para gerar uma ação de conversão específica.

Listar fontes de comparativos de mercado

O método ListBenchmarksSources recupera as fontes de comparativo de mercado disponíveis. Especifique os tipos de origem a serem recuperados usando BenchmarksSourceType:

• INDUSTRY_VERTICAL: classificações de segmentos do setor (por exemplo, "Technology" ou "Finance").
• CATEGORY (na v25 e em versões mais recentes): categorias de produtos e serviços (por exemplo, "/Apparel/Clothing"). Elas podem ser usadas como filtros para definir o escopo do comparativo de mercado ao comparar com todos os anunciantes.

A resposta retorna uma lista de objetos BenchmarksSourceMetadata que contêm:

• IndustryVerticalInfo: contém industry_vertical_name, industry_vertical_id e parent_industry_vertical_id (se aplicável).
• CategoryInfo (na v25 e mais recentes): contém category_name, category_id e category_path (a hierarquia de categorias completa).

Gerar métricas de comparativo de mercado

Chame GenerateBenchmarksMetrics para comparar as métricas de anúncios do YouTube de um cliente com os comparativos de mercado.

Parâmetros de solicitação

Um GenerateBenchmarksMetricsRequest define o escopo da análise. No mínimo, é preciso especificar um customer_id do cliente, um location geográfico (LocationInfo), um benchmarks_source (um industry_vertical_id ou, na v25 e versões mais recentes, um all_advertisers com escopo definido por category_filter) e um product_filter. Você também pode:

• Forneça um date_range (se omitido, os dados serão retornados para o trimestre mais recente com dados disponíveis).
• Agrupar métricas com um breakdown_definition.
• Especifique um código ISO 4217 de três caracteres currency_code (se omitido, as métricas monetárias, como CPM e custo, serão definidas como USD).
• Especifique um nome de customer_benchmarks_group definido pelo usuário para o cliente que está sendo planejado.
• Solicite recursos adicionais, como PERCENTILE_DATA por meio de supplemental_data (na v25 e em versões mais recentes).

Para ver as definições e os requisitos completos dos parâmetros, consulte a documentação de referência de GenerateBenchmarksMetricsRequest.

Detalhamentos de datas

É possível agrupar métricas definindo breakdown_definition.date_breakdown usando BenchmarksTimeGranularity. Quando date_breakdown está definido, date_range em GenerateBenchmarksMetricsRequest é obrigatório e precisa se alinhar aos limites da granularidade selecionada:

• WEEK: agrega métricas por semana. O date_range precisa começar em um domingo e terminar em um sábado (isso é diferente da ISO 8601).
• MONTH: agrega métricas por mês. O date_range precisa começar no primeiro dia do mês e terminar no último dia do mês.
• QUARTER: agrega métricas por trimestre. O date_range precisa começar no primeiro dia do trimestre e terminar no último dia do trimestre.

Métricas de resposta

O GenerateBenchmarksMetricsResponse retorna:

• customer_metrics (do tipo CustomerMetrics na v25 e versões mais recentes; do tipo Metrics contendo apenas average_rate_metrics na v24 e versões anteriores): métricas que representam a performance do anúncio do YouTube de um cliente, incluindo:
  • average_rate_metrics: métricas de taxa média para o cliente.
  • share_metrics (na v25 e mais recentes): métricas de presença relativa no mercado (share_of_voice e share_of_spend). Preenchido apenas quando benchmarks_source seleciona all_advertisers = true (com category_filter definido) e date_range está dentro de supported_dates_for_all_metrics.
  • aggregate_metrics (na v25 e em versões mais recentes): totais agregados para o cliente (como cost, impressions, clicks e video_trueview_views).
  • percentile_metrics (na v25 e em versões mais recentes): níveis de percentil de posição competitiva em dimensões importantes.
• average_benchmarks_metrics: métricas de taxa agregadas (RateMetrics) na origem de comparativo de mercado selecionada.
• breakdown_metrics: uma lista de métricas segmentadas pelos detalhamentos definidos em breakdown_definition.

Para ver as especificações completas dos campos, consulte a documentação de referência GenerateBenchmarksMetricsResponse.

Métricas de percentil

Observação: supplemental_data (BenchmarksSupplementalData) e percentile_metrics estão disponíveis na v25 e em versões mais recentes.

As métricas de percentil representam a posição competitiva de um cliente como níveis de percentil entre outros anunciantes na análise de escopo.

Pré-requisitos

Para recuperar métricas de percentil, sua solicitação precisa atender aos seguintes requisitos:

1. Origem dos comparativos de mercado: benchmarks_source precisa selecionar all_advertisers = true.
2. Filtro de categoria: category_filter precisa ser fornecido, contendo um ou mais category_ids válidos recuperados de ListBenchmarksSources.
3. Dados complementares: adicione PERCENTILE_DATA ao campo supplemental_data em GenerateBenchmarksMetricsRequest.

Níveis de percentil

A performance de um cliente é classificada em um dos seguintes valores de tipo enumerado BenchmarksCustomerPercentileTier:

• DEVELOPING: abaixo do 10º percentil ([0%, 10%)).
• ENTRY_LEVEL: do 10º ao 25º percentil ([10%, 25%)).
• EMERGING_PLAYER: percentil 25 a 50 ([25%, 50%)).
• COMPETITOR: percentil 50 a 75 ([50%, 75%)).
• STRONG_COMPETITOR: 75º ao 90º percentil ([75%, 90%)).
• MARKET_LEADER: no 90º percentil ou acima dele ([90%, 100%]).

Exemplo de solicitação

O exemplo a seguir ilustra um payload de solicitação JSON REST para gerar métricas de comparativo de mercado com níveis de percentil para um usuário que compara a performance dos anúncios do YouTube do cliente com outros anunciantes que veiculam anúncios na categoria /Apparel/Clothing:

{
  "customerId": "1234567890",
  "location": {
    "geoTargetConstant": "geoTargetConstants/2840"
  },
  "benchmarksSource": {
    "allAdvertisers": true
  },
  "categoryFilter": {
    "categoryIds": ["10176"]
  },
  "productFilter": {
    "marketingObjectiveList": {
      "marketingObjectives": ["AWARENESS", "CONSIDERATION"]
    }
  },
  "supplementalData": [
    "PERCENTILE_DATA"
  ]
}

A resposta, incluindo os dados de percentil adicionais solicitados:

{
  "customerMetrics": {
    "averageRateMetrics": {
      "averageCpm": 5.42,
      "clickThroughRate": 0.0185
    },
    "shareMetrics": {
      "shareOfVoice": 0.0345,
      "shareOfSpend": 0.0410
    },
    "aggregateMetrics": {
      "cost": 15200.0,
      "impressions": 2800000.0,
      "clicks": 51800.0
    },
    "percentileMetrics": {
      "costPercentileTier": "STRONG_COMPETITOR",
      "impressionsPercentileTier": "STRONG_COMPETITOR",
      "clicksPercentileTier": "MARKET_LEADER",
      "videoTrueviewViewsPercentileTier": "COMPETITOR",
      "viewableImpressionsPercentileTier": "STRONG_COMPETITOR",
      "interactionsPercentileTier": "MARKET_LEADER",
      "engagementsPercentileTier": "COMPETITOR"
    }
  },
  "averageBenchmarksMetrics": {
    "averageRateMetrics": {
      "averageCpm": 6.15,
      "clickThroughRate": 0.0142
    }
  }
}

Tratamento de erros

Ao chamar o BenchmarksService, talvez você encontre erros específicos de consultas de comparativos de mercado em BenchmarksError:

• MAX_QUERY_COMPLEXITY_EXCEEDED: a combinação de entradas solicitadas é muito complexa para ser processada. Para reduzir a complexidade da consulta:
  • Selecione uma fonte de comparativo de mercado ou um filtro de categoria mais específico ou granular.
  • Encurte o date_range solicitado.
  • Reduza o número de produtos em product_filter.
• NO_METRICS_FOUND (na v25 e em versões mais recentes): nenhuma métrica foi encontrada para a combinação de entradas solicitada (por exemplo, uma categoria de nicho em um local e período específicos em que nenhum anunciante veiculou campanhas). Tente ajustar a categoria, o local, o período ou os produtos.

Para práticas recomendadas e tratamento de erros gerais de API, consulte o guia de tratamento de erros.

Issue Tracker do Google

Use o Issue Tracker do Google para fazer perguntas de suporte, informar bugs ou enviar solicitações de recursos. O Google rastreia, prioriza e publica atualizações sobre suas solicitações diretamente no Issue Tracker. Para mais informações, consulte Criar um problema no Issue Tracker do Google.

Crie um problema usando um dos seguintes modelos do Issue Tracker:

• Fazer uma pergunta geral de suporte ou enviar feedback sobre a documentação
• Informar um bug técnico
• Enviar uma solicitação de recurso da API

Preencha todos os campos do modelo com informações detalhadas para que o Google possa reproduzir e priorizar sua solicitação. O Google pode encerrar relatórios incompletos e pedir que você envie um novo problema com os detalhes que faltam.