Como automatizar relatórios do Google Analytics com Python

Faaala devs, marqueteiros ou entusiastas de automação! 🚀

Por que automatizar relatórios de marketing vale a pena?

Pensa aí: quantas horas por mês você gasta com relatórios manuais?

• ✅ Economize muitas horas mensais: tempo que volta para análise estratégica e criatividade.

• ✅ Elimine erros humanos: o famoso "copia e cola" manual é onde os erros acontecem. Scripts não erram.

• ✅ Dados sempre atualizados: precisa dos números de ontem? Rode o script e tenha o relatório em segundos.

• ✅ Escale sem esforço: o mesmo script pode ser adaptado para múltiplos clientes ou projetos.

O que você precisa para começar

Conhecimentos básicos

• Python: se você nunca usou, tudo bem. Vamos te guiar.

• GA4: familiaridade com a interface e conceitos como métricas e dimensões.

• APIs: APIs são como garçons digitais. Você faz um pedido (request) e elas trazem os dados do "restaurante" (Google Analytics).

Ferramentas e contas necessárias

• Python 3.7 ou superior instalado na sua máquina.

• Um editor de código (sugerimos o Visual Studio Code).

• Acesso a uma propriedade do Google Analytics 4 (GA4).

• Uma conta no Google Cloud Console (é gratuito para começar).

Passo 1 - configurar o Google Cloud Console

📍 Você está aqui: passo 1 de 6

Criar projeto e ativar a API

1. Acesse o Google Cloud Console.

2. No topo, clique em "selecionar um projeto" e depois em "novo projeto". Dê um nome claro (ex: automacao-relatorios-mkt).

3. Com o projeto selecionado, vá ao menu lateral e clique em "APIs e serviços" > "biblioteca".

4. Na barra de busca, procure por Google Analytics Data API.

5. Clique nela e depois no botão azul "ativar".

Gerar credenciais de autenticação

1. Volte para "APIs e serviços" > "credenciais".

2. Clique em "+ criar credenciais" e escolha "conta de serviço" (service account).

3. Dê um nome para a conta (ex: python-ga4-script) e clique em "criar e continuar". Pode pular as etapas opcionais.

4. Após criada, clique na conta de serviço recém-criada.

5. Vá para a aba "chaves" (keys).

6. Clique em "adicionar chave" > "criar nova chave".

7. Selecione o tipo JSON e clique em "criar".

A etapa que 90% das pessoas esquecem

1. Copie o e-mail da conta de serviço (algo como python-ga4-script@automacao-relatorios-mkt.iam.gserviceaccount.com). Você encontra esse email na tela de detalhes da conta de serviço no Google Cloud, ou no campo "client_email" dentro do arquivo JSON que você baixou.

2. Vá para o seu Google Analytics.

3. Clique em "administrador" (roda dentada no canto inferior esquerdo).

4. Em "propriedade", clique em "gerenciamento de acesso à propriedade".

5. Clique no botão azul "+" e em "adicionar usuários".

6. Cole o e-mail da conta de serviço e selecione a função "leitor" (viewer).

7. Clique em "adicionar".

Passo 2 - Instalar bibliotecas Python necessárias

📍 Você está aqui: passo 2 de 6

pip install google-analytics-data pandas openpyxl

• google-analytics-data: a biblioteca oficial do Google para interagir com a API do GA4.

• pandas: a ferramenta padrão do mercado para manipulação de dados em Python.

• openpyxl: necessário para o pandas exportar arquivos no formato Excel (.xlsx).

Passo 3 - Conectar seu script com a API do GA4

📍 Você está aqui: passo 3 de 6

from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.oauth2 import service_account

# --- CONFIGURAÇÕES ---
# 1. Seu Property ID do GA4
# ⚠️ SUBSTITUA pelo seu ID (encontrado em Admin > detalhes da propriedade)
PROPERTY_ID = "123456789"

# 2. Caminho para o arquivo de credenciais
CREDENTIALS_FILE = 'credentials.json'
# ---------------------

# Configurar credenciais e iniciar o cliente da API
print("🚀 Conectando à API do Google Analytics...")
try:
    credentials = service_account.Credentials.from_service_account_file(
        CREDENTIALS_FILE)
    client = BetaAnalyticsDataClient(credentials=credentials)
    print("✅ Conectado com sucesso!")
except FileNotFoundError:
    print(f"❌ Erro: Arquivo de credenciais não encontrado em {CREDENTIALS_FILE}")
    exit() # Encerra o script se não encontrar as credenciais
except Exception as e:
    print(f"❌ Erro ao conectar: {e}")
    exit()

Passo 4 - Extrair seus primeiros dados do Analytics

📍 Você está aqui: passo 4 de 6

• Dimensions (dimensões): características dos dados (ex: data, cidade, fonte de tráfego).

• Metrics (métricas): números (ex: sessões, usuários, conversões, receita).

from google.analytics.data_v1beta.types import DateRange, Dimension, Metric, RunReportRequest

# Construir a requisição de relatório
request = RunReportRequest(
    property=f"properties/{PROPERTY_ID}",
    dimensions=[
        Dimension(name="date"),
        Dimension(name="sessionSource")
    ],
    metrics=[
        Metric(name="sessions"),
        Metric(name="activeUsers")
    ],
    # Definir o período (aceita "7daysAgo", "today", "yesterday", ou datas YYYY-MM-DD)
    date_ranges=[DateRange(start_date="7daysAgo", end_date="today")],
)

# Executar a requisição
print("📊 Extraindo dados...")
try:
    response = client.run_report(request)
except Exception as e:
    print(f"❌ Erro ao extrair dados: {e}")
    # Se der erro (ex: permissão negada), a variável 'response' não será criada.
    response = None

# Exibir os resultados brutos (apenas para conferência inicial)
if response:
    print("\n🔎 Resultados brutos (preview):")
    # Mostra apenas as primeiras 5 linhas para conferência
    for i, row in enumerate(response.rows):
        if i >= 5: break
        # row.dimension_values[0] = date
        # row.dimension_values[1] = sessionSource
        # row.metric_values[0] = sessions
        print(f"{row.dimension_values[0].value} | "
              f"{row.dimension_values[1].value} | "
              f"Sessões: {row.metric_values[0].value}")

Passo 5 - Transformar dados em tabelas com Pandas

📍 Você está aqui: passo 5 de 6

import pandas as pd

def ga_to_dataframe(response):
    """Converte resposta GA4 em dataframe do Pandas."""
    # Cabeçalhos das colunas
    columns = [h.name for h in response.dimension_headers]
    columns += [h.name for h in response.metric_headers]

    # Linhas de dados
    rows = []
    for row in response.rows:
        r = [d.value for d in row.dimension_values]
        r += [m.value for m in row.metric_values]
        rows.append(r)

    return pd.DataFrame(rows, columns=columns)

# Converter para dataframe (se a extração foi bem-sucedida)
if response:
    df = ga_to_dataframe(response)
    print("\n🐼 Dataframe criado:")
    print(df.head())

Passo 6 - Exportar para Excel e CSV

📍 Você está aqui: passo 6 de 6

# Verifica se o dataframe foi criado e não está vazio
if 'df' in locals() and not df.empty:
    print("\n💾 Exportando relatórios...")

    # Exportar para CSV
    # encoding='utf-8-sig' garante que acentos funcionem bem no Excel brasileiro
    # index=False remove a coluna de índice do pandas
    df.to_csv('relatorio_ga4.csv', index=False, encoding='utf-8-sig')
    print("✅ Relatório exportado para relatorio_ga4.csv")

    # Exportar para Excel (xlsx)
    df.to_excel('relatorio_ga4.xlsx', index=False, sheet_name='Dados GA4')
    print("✅ Relatório exportado para relatorio_ga4.xlsx")

    print("\n🚀 Missão cumprida! Automação concluída.")
else:
    print("\n⚠️ Nenhum dado para exportar. Verifique os passos anteriores.")

Casos de uso práticos para aplicar agora

Relatório semanal de fontes de tráfego

dimensions=[
    Dimension(name="sessionSource"),
    Dimension(name="sessionMedium")
]
metrics=[
    Metric(name="sessions"),
    Metric(name="conversions"),
    Metric(name="totalRevenue")
]

Performance de landing pages

dimensions=[
    # landingPagePlusQueryString mostra a URL completa, incluindo parâmetros UTM
    Dimension(name="landingPagePlusQueryString")
]
metrics=[
    Metric(name="sessions"),
    Metric(name="bounceRate"),
    Metric(name="averageSessionDuration")
]

Análise de público por localização

dimensions=[
    Dimension(name="country"),
    Dimension(name="city")
]
metrics=[
    Metric(name="activeUsers"),
    Metric(name="eventCount")
]

Erros comuns e como resolver rapidamente

Erro 1: PERMISSION_DENIED: User does not have sufficient permissions

Erro 2: INVALID_ARGUMENT: ...dimension and metric combination is incompatible

Erro 3: FileNotFoundError ou "Arquivo de credenciais não encontrado"

Deu o play no foguete? Hora de decolar de vez!

Sua próxima missão: de automatizador a arquiteto digital

• Construir suas próprias APIs, em vez de apenas consumir as do Google, para integrar qualquer sistema que você imaginar.

• Salvar dados do GA4 em um banco de dados próprio, criando um ativo histórico para análises preditivas.

• Criar notificações em tempo real para ser avisado via Slack ou Discord quando uma meta de marketing for atingida.