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. Em seguida, combine esses dados com informações de conversão ou receita brutas, não filtradas e não atribuídas do seu CRM interno, de um ponto de venda (PDV) ou de bancos de dados de vendas internos.

Arquitetura de fluxo de trabalho de API recomendada

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

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

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

• 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 a GeoX, os anunciantes extraem métricas de custo usando a API Google Ads em vez de conversões atribuídas (que devem vir de sistemas internos de CRM ou 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
  

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 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
  

  Se preferir, para fazer a junção localmente no código, baixe o 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. Divida metrics.cost_micros por 1.000.000 para gerar o valor padrão da moeda exigido no arquivo de upload.

IDs de local geográfico 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 pesquisar e transmitir o ID GeoTargetConstant exato (geoTargetConstants/ID) 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 da DMA	ID 200501 (para Nova York)	Código da 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 strings de data ISO-8601 no formato YYYY-MM-DD. No seu pipeline de ETL, serializa 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.
• Junção de dados de conversão:ao fazer a junção com dados de conversão de um sistema de CRM interno ou bancos de dados de vendas internos, verifique se os dados de conversão têm as seguintes propriedades para garantir o processamento de dados sem problemas com os dados da API Google Ads e da 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, o CEP de entrega do cliente precisa corresponder 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 rastrear a receita líquida com valores negativos para reembolsos, use os números brutos no experimento e aplique uma proporção de reembolso depois.