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, um ponto de venda (PDV) ou 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 GoogleAdsService, especificamente os métodos Search ou SearchStream.

• Recurso:consulte geographic_view para saber onde o usuário estava fisicamente localizado ou interessado, 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.

• 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 um CRM interno ou 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
  

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 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 geo_target_constant recurso:

  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 junção localmente no código, faça o download do CSV de segmentações por área geográfica 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.

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 pesquisar e transmitir o ID GeoTargetConstant exato (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ório (GeoTargetConstant)	Formato legado (não usar)
Região 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 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 reformam 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 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 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 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 ao 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 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.