Extrair dados geográficos para experimentos

Para extrações de dados automatizadas ou em grande escala para experimentos GeoX, use a API Google Ads para extrair dados de custo e gasto. Em seguida, combine esses dados com dados de conversão ou receita brutos, não filtrados e não atribuídos do seu CRM interno, de um ponto de venda (PDV) ou de bancos de dados de vendas internos.

Arquitetura recomendada do fluxo de trabalho da API

Para extrair com precisão os dados de campanha e custo por segmentos geográficos, siga esta arquitetura:

• Serviço: use GoogleAdsService, especificamente os métodos Search ou SearchStream.

• Recurso: consulte geographic_view para saber onde o usuário estava fisicamente localizado ou em que ele tinha interesse, o que normalmente é o padrão para experimentos GeoX. Como alternativa, consulte location_view para conferir o desempenho com base em locais de segmentação específicos da campanha.

  Observação: não use campaign_location_target_report, já que esse relatório legado da API AdWords foi desativado.

• Campos a serem incluídos:

  • campaign.id
  • segments.date
  • segments.geo_target_city (ou região ou país, dependendo da granularidade do GeoX)
  • metrics.cost_micros

• Exemplo de consulta GAQL: para o GeoX, os anunciantes extraem métricas de custo usando a API Google Ads em vez de conversões atribuídas (que devem vir de CRM interno ou sistemas de terceiros). Use a seguinte consulta:

  SELECT
    campaign.id,
    segments.date,
    segments.geo_target_city,
    metrics.cost_micros
  FROM geographic_view
  WHERE segments.date DURING LAST_30_DAYS
  

  Observação: geographic_view só retorna linhas para segmentos geográficos que registraram impressões ou gastos em uma determinada data. Para incluir dias e regiões com gasto zero na série temporal do GeoX, faça uma mesclagem externa à esquerda no pipeline de dados com o produto cartesiano completo de datas e regiões de segmentação.

Observação: se você extrair métricas de conversão do Google Ads, vai extrair conversões atribuídas, ou seja, vai analisar apenas as vendas que o algoritmo do Google já reivindicou. O uso de dados atribuídos é fortemente desencorajado no GeoX porque a lógica de atribuição distorce a medição causal.

Pós-processamento e extração de dados

• Mapeamento de segmentos geográficos: a API não retorna nomes em texto simples (como "Nova York") ou códigos curtos (como "501" ou "ES") em vistas de relatórios. Campos como segments.geo_target_city ou segments.geo_target_country retornam uma string de nome de recurso que aponta para um GeoTargetConstant (por exemplo, geoTargetConstants/1023191). Extraia o ID numérico (1023191) e consulte o recurso geo_target_constant:

  SELECT
    geo_target_constant.id,
    geo_target_constant.name,
    geo_target_constant.canonical_name
  FROM geo_target_constant
  WHERE geo_target_constant.id = 1023191
  

  Como alternativa, para realizar a mesclagem localmente no código, faça o download do CSV de segmentações por área geográfica estáticas em Segmentações por área geográfica.

• Conversão de custo: a API retorna valores de custo em micros. Divida metrics.cost_micros por 1.000.000 para gerar o valor de moeda padrão necessário no arquivo de upload.

IDs de localização geográfica para mutações de segmentação

Ao executar mutações de segmentação por local de campanha ou grupo de anúncios, os anunciantes precisam procurar e transmitir o ID exato de GeoTargetConstant (geoTargetConstants/ID) para as regiões selecionadas. Não é possível transmitir códigos ISO ou Nielsen brutos.

Tipo de região	ID da API obrigatória (GeoTargetConstant)	Formato legado (não usar)
Região de DMA	ID 200501 (para Nova York)	Código Nielsen (por exemplo, 501 para Nova York)
País	ID 2724 (para a Espanha)	Código ISO (por exemplo, "ES" para Espanha)

Práticas recomendadas e erros comuns de formatação

• Formatação de data: o campo segments.date retorna strings de data ISO-8601 no formato YYYY-MM-DD. No pipeline de ETL, serialize os campos de data explicitamente como strings YYYY-MM-DD e evite abrir arquivos CSV exportados em aplicativos de planilha que reformatam automaticamente as colunas de data.
• Zeros à esquerda em códigos postais: trate códigos postais e CEPs (por exemplo, 01234) como tipos de string (VARCHAR ou STRING) em todo o pipeline de dados, em vez de números inteiros, para que os zeros à esquerda nunca sejam removidos.
• Agregação: se você estiver realizando um estudo com várias células, forneça métricas de gastos separadas para cada grupo de tratamento.
• Mesclagem de dados de conversão: ao mesclar dados de conversão de um sistema de CRM interno ou de bancos de dados de vendas internos, verifique se os dados de conversão têm as seguintes propriedades para garantir o tratamento de dados sem problemas com os dados da API Google Ads e do GeoX:
  • Série temporal diária: os dados precisam ser agregados por dia.
  • Nível geográfico: cada conversão precisa ser mapeada para as unidades geográficas exatas que você está testando (por exemplo, correspondendo o CEP de envio do cliente ao DMA ou ao cluster postal usado no design).
  • Valores brutos: os dados precisam ser valores absolutos não negativos, como receita bruta ou contagens brutas de conversões. Se o CRM rastreia a receita líquida com valores negativos para reembolsos, use os números brutos no experimento e aplique uma proporção de reembolso posteriormente.