Extrair dados geográficos para experimentos

Para extrações de dados automatizadas ou em grande escala para experimentos do GeoX, use a API Google Ads para extrair dados de custo e gasto. Você precisará combinar isso 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 de fluxo de trabalho da API recomendada

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

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

• Recurso:consulte a geographic_view para saber onde o usuário estava fisicamente localizado ou interessado, que normalmente é o padrão para experimentos do GeoX. Como alternativa, consulte a location_view para conferir a performance com base em locais específicos segmentados pela campanha.

  Observação: não use o campaign_location_target_report, porque 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 precisam extrair métricas de custo usando a API Google Ads em vez de conversões atribuídas (que devem vir do CRM interno ou de sistemas de terceiros). Você pode usar 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: se você extrair métricas de conversão do Google Ads, estará extraindo atribuídas conversões. Isso significa que você só está analisando as vendas que o algoritmo do Google já reivindicou o crédito. O uso de dados atribuídos é fortemente desencorajado no GeoX porque a lógica de atribuição vai influenciar a medição causal real.

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

• Mapeamento de segmentos geográficos:a API não retorna nomes de texto simples (como "Nova York") ou códigos curtos (como "501" ou "ES") nas visualizações de relatórios. Campos como segments.geo_target_city ou segments.geo_target_country retornam uma string de nome de recurso que aponta para uma GeoTargetConstant (por exemplo, geoTargetConstants/1023191). Os desenvolvedores podem consultar a geo_target_constant tabela diretamente:

  SELECT geo_target_constant.canonical_name
  FROM geo_target_constant
  WHERE geo_target_constant.resource_name = 'geoTargetConstants/{extracted_id}'
  

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

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

Códigos de segmentação (DMA e país)

Ao executar mutações de segmentação, os anunciantes precisam pesquisar e transmitir o ID GeoTargetConstant exato das regiões selecionadas. Não é possível transmitir códigos ISO ou Nielsen brutos.

Tipo de região	ID da API obrigatório (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 a Espanha)

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

• Formatação de data:o campo segments.date retorna dados no formato YYYY-MM-DD. Aplicativos de planilha, como o Excel, geralmente mudam os formatos de data automaticamente. Faça o upload do arquivo para o Planilhas Google primeiro para garantir que o período seja lido com precisão no formato YYYY-MM-DD necessário.
• Zeros à esquerda:verifique se os zeros à esquerda nos códigos postais (por exemplo, 01234) não foram descartados. Use o "Formato de número personalizado" no Planilhas Google para forçar uma string de cinco dígitos.
• Agregação:se você estiver executando um estudo de várias células, forneça métricas de gastos separadas para cada braço de tratamento.
• Como unir dados de conversão:ao unir 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 processamento de dados contínuo 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 de conversão bruta. Se o CRM rastrear a receita líquida com valores negativos para reembolsos, use os números brutos para o experimento e aplique uma proporção de reembolso mais tarde.