Como criar análises de SEO para um site multilíngue com a API do GSC e o BigQuery

Gostaria de experimentar o Octo Browser com desconto?
Use o código promocional OCTOBLOG e ganhe 30% de desconto em qualquer assinatura. Esta oferta é válida somente para novos usuários.

Por que se afastar das interfaces web

Um sistema confiável de análise de SEO começa com a eliminação das exportações manuais. A interface do Google Search Console é conveniente para verificar rapidamente certas métricas, mas suas capacidades são insuficientes para uma análise profunda de produto.

A API do GSC possibilita obter dados em um nível mais granular — por URLs individuais, consultas de pesquisa e outras dimensões. Isso permite que você trabalhe não apenas com relatórios agregados, mas também com os dados subjacentes a partir dos quais você pode construir seus próprios recortes e métricas.

Para entender as vantagens desta arquitetura, é importante considerar vários fatores-chave.

Cardinalidade dos dados e limitações da interface web

Um dos principais problemas com a interface do GSC é a quantidade limitada de dados que ela exibe. Isso é especialmente crítico para um projeto multilíngue: quando há um grande número de páginas, países, dispositivos e consultas, uma parte significativa das informações fica de fora do relatório padrão.

É aqui que a cardinalidade é importante — o número de combinações únicas de parâmetros em um conjunto de dados. Por exemplo, se um site opera em 10 idiomas, recebe tráfego de 50 países, usa 3 tipos de dispositivos e se posiciona para 10.000 consultas de pesquisa, o número de combinações possíveis pode chegar a milhões de linhas.

Trabalhar com esse volume de dados através da interface web é praticamente impossível. A API permite que você recupere consideravelmente mais dados e divida a exportação em segmentos separados. Através de filtragem e processamento sequencial, você pode coletar não apenas a parte superior dos resultados, mas também a cauda longa de consultas e URLs que geralmente é perdida nos relatórios padrão.

Data Lake e armazenamento histórico

O Google Search Console armazena dados históricos em sua interface apenas nos últimos 16 meses, o que é insuficiente para análises de SEO de longo prazo.

Um data warehouse dedicado, como o BigQuery, resolve esse problema. Você pode salvar regularmente dados brutos obtidos através da API lá, sem ficar limitado pelo período de retenção na interface do GSC. Isso fornece um banco de dados histórico de SEO que pode ser usado para análises de longo prazo, construção de relatórios e reprocessamento de dados em qualquer dimensão necessária.

Dependência de serviços externos e o custo de escalabilidade

Conectores ETL prontos para uso podem ser usados para automatizar as exportações de dados, por exemplo, serviços SaaS como Supermetrics ou Fivetran. Eles permitem que você configure transferências de dados rapidamente sem desenvolvimento interno, mas à medida que o projeto cresce, essa abordagem pode se tornar cara e vincular sua infraestrutura de forma muito estreita a um serviço específico.

As plataformas SaaS cobram por seus serviços com base no volume de linhas processadas ou no número de conectores. Quando seu projeto multilíngue começa a gerar gigabytes de dados brutos de SEO por dia, o custo de tal serviço pode exceder várias vezes o custo de armazenar os dados no BigQuery e alugar um servidor pequeno para scripts Python.

Além disso, quanto mais profundamente um serviço está integrado no processo de coleta e transformação de dados, mais difícil se torna substituí-lo posteriormente: a migração pode exigir a reconfiguração dos conectores, da lógica de processamento e dos relatórios.

Nível de granularidade dos dados

Ao coletar dados por meio da API, é importante preservar o máximo de detalhes possível. Se você combinar dados já na etapa de exportação, não conseguirá reconstruir as dimensões originais posteriormente.

Por exemplo, ao projetar um banco de dados de SEO, você deve armazenar parâmetros como tipo de Device e Country separadamente. Se o script solicitar dados sem um detalhamento por país, o GSC retornará o número total de cliques para a consulta. Depois disso, será impossível determinar quantos cliques vieram da Alemanha e quantos vieram da França.

Por isso é melhor armazenar os dados de forma detalhada e combiná-los e calcular as métricas finais apenas na etapa de análise ou visualização. Isso preserva a capacidade de construir quaisquer recortes de dados necessários no futuro, mesmo que não tenham sido originalmente previstos nos relatórios.

Limitações da API do GSC ao exportar grandes volumes de dados

À primeira vista, trabalhar com a API do GSC parece simples: autorizar o script, recuperar os dados, salvá-los no banco de dados e passar para a análise. Na prática, grandes projetos rapidamente se deparam com as limitações técnicas da API.

Se você tentar exportar grandes volumes de dados sem levar em conta essas limitações, poderá encontrar timeouts, erros do tipo 429 Too Many Requests e exportações incompletas. Como resultado, apenas parte dos dados chegará ao data warehouse, e o próprio sistema se tornará instável.

É por isso que o pipeline deve prever limites de API, atrasos na atualização de dados, cotas de consulta e mecanismos de nova tentativa para solicitações com falha com antecedência. Vamos dar uma olhada nas principais limitações da API do GSC e como trabalhar com elas corretamente.

O limite de 50.000 linhas e segmentação de exportação

De acordo com a documentação do Google, o parâmetro rowLimit permite recuperar no máximo 25.000 linhas em uma única solicitação. O parâmetro startRow é usado para paginação: você pode solicitar inicialmente as primeiras 25.000 linhas e depois as próximas 25.000.

No entanto, existe uma limitação adicional: a soma de startRow + rowLimit não pode exceder 50.000. Portanto, para uma única data e uma combinação selecionada de parâmetros, você não pode recuperar a linha 50.001 dessa maneira.

Se a cardinalidade diária de seus dados exceder 50.000 linhas, você precisará dividir a exportação em segmentos separados usando Dimension Filters. Por exemplo, você pode consultar dados separadamente para pastas de idiomas — /de/, /fr/, e assim por diante, ou dividir adicionalmente URLs por padrões usando expressões regulares.

Isso permite obter o conjunto de dados completo por meio de várias solicitações independentes direcionadas a diferentes segmentos de dados.

Atraso de dados e trabalho com dataState

A API do GSC tem um atraso sistemático na atualização dos dados de 48 a 72 horas. Portanto, ao exportar dados diariamente, é importante distinguir entre dados preliminares e finais.

O parâmetro dataState controla isso. Ele tem dois valores:

• "final" (padrão) — retorna apenas dados totalmente agregados e validados.

• "all" — inclui dados recentes que ainda não passaram pelo processamento final.

Isso cria um trade-off entre velocidade e precisão ao construir o pipeline. Vamos analisar ambos os cenários.

• Usando dataState: "final" (o comportamento padrão). Neste modo, os dados das últimas 24 horas podem ainda não estar disponíveis. Se o seu script tentar exportar yesterday usando o valor padrão, a API retornará uma array vazia. Você precisa aplicar um offset fixo de current_date — 3 days.

• Usando dataState: "all". Você receberá o conjunto de dados necessário para as 24 horas anteriores. No entanto, o Google alerta que os dados recentes são preliminares. O sistema ainda não consolidou todas as duplicatas, filtrou bots de spam ou recalculou anomalias. Após 2–3 dias, esses números mudarão nos próprios servidores do Google.

Como isso pode afetar sua arquitetura de armazenamento: se o seu script Python simplesmente anexar dados brutos recentes ao BigQuery, seu banco de dados histórico ficará distorcido. Ao gravar métricas "recentes", você está armazenando um rascunho que nunca corresponderá exatamente aos relatórios finais na interface do GSC.

Portanto, para análises operacionais, é melhor usar uma abordagem em duas etapas:

1. Exporte dados do dia anterior usando dataState: "all".

2. Ao mesmo tempo, o script deve reexportar dados para current_date — 4 days usando dataState: "final".

3. No BigQuery, em vez de um simples Append, use o operador MERGE (ou lógica de Upsert). O script deve encontrar os dados preliminares de quatro dias antes no banco de dados e substituí-los pelos valores finais consolidados.

Esta abordagem permite ver métricas recentes no painel, preservando um banco de dados histórico correto após o processamento final dos dados.

Limites de API e backoff exponencial

A API do GSC limita o número de solicitações para proteger sua infraestrutura de carga excessiva. A API do GSC possui cotas rígidas: 50 consultas por segundo (QPS) e 1.200 consultas por minuto (QPM) por projeto. Portanto, essas restrições precisam ser levadas em consideração com antecedência ao realizar exportações em larga escala.

O problema é especialmente perceptível quando os dados precisam ser divididos em centenas de segmentos para contornar o limite de 50.000 linhas. Para acelerar o processo, os desenvolvedores geralmente usam solicitações assíncronas (asyncio) ou pools de threads (ThreadPoolExecutor). Mas isso pode esgotar rapidamente o limite de 50 QPS, e a API começa a retornar erros de 429 Too Many Requests ou 503 Service Unavailable.

Um simples atraso usando time.sleep() não funciona muito bem aqui. Se várias threads paralelas receberem um erro ao mesmo tempo e depois dormirem pelo mesmo período, elas serão retomadas quase simultaneamente e criarão outro pico de tráfego.

A arquitetura correta do script deve incluir um padrão de backoff exponencial com ruído aleatório adicionado (Jitter). Isso faz com que o intervalo entre as solicitações de nova tentativa aumente gradualmente. Nem todas as threads tentarão novamente ao mesmo tempo, reduzindo a chance de excederem os limites.

Em Python, você não precisa necessariamente implementar essa lógica manualmente: você pode usar decoradores da biblioteca tenacity.

Coleta de dados de SEO para subdomínios e pastas de idiomas

Depois de levar em consideração os limites e atrasos da API do GSC, a próxima pergunta importante é como exatamente o site multilíngue está estruturado. A estrutura do projeto afeta diretamente a lógica de exportação, normalização e combinação de dados.

No SEO multilíngue, existem duas abordagens polares para a estrutura do site: subdomínios nacionais e pastas de idiomas. Para o usuário, a diferença é mínima, mas para a construção de exportações, as diferentes estruturas podem mudar completamente a abordagem.

Subdomínios e domínios separados

Se as versões de idioma estiverem hospedadas em domínios separados (site.de, site.fr) ou subdomínios (de.site.com, fr.site.com), os dados de cada versão deverão ser coletados como dados de um recurso separado.

Por que isso é útil para o negócio? O isolamento regional permite controlar o orçamento de rastreamento (crawl budget) de forma mais rígida. Um mecanismo de pesquisa não gastará o orçamento de rastreamento do bot alemão escaneando a versão francesa do site. Do ponto de vista de SEO, este é o caminho mais seguro para a escalabilidade.

Para o pipeline de análise, isso cria dois problemas:

• Mais pontos de conexão. Se o projeto tiver 10 versões de idioma, o script precisará consultar vários recursos do GSC sequencialmente ou em paralelo. Quanto mais fontes houver, mais importantes se tornam as cotas de API, o tratamento de erros e a resiliência de toda a arquitetura de exportação.

• Complexidade de normalização de URL (união de dados). Páginas com a mesma finalidade em domínios diferentes terão endereços diferentes — por exemplo, site.de/product e site.fr/product. Para comparar o desempenho delas como uma única entidade, suas URLs precisam ser normalizadas.

Na biblioteca Pandas para Python, essa normalização se parece com isso:

import pandas as pd
from urllib.parse import urlparse

# Keep only the path for stitching metrics across countries
df['normalized_url'] = df['page'].apply(lambda x: urlparse(x).path) 
# Result: /product

import pandas as pd
from urllib.parse import urlparse

# Keep only the path for stitching metrics across countries
df['normalized_url'] = df['page'].apply(lambda x: urlparse(x).path) 
# Result: /product

Sem essa normalização, as métricas para diferentes localizações permanecerão separadas em diferentes URLs. Isso dificultará o cálculo do desempenho geral da mesma página ou modelo em diferentes idiomas.

Pastas de idiomas e segmentação de dados

Se as versões de idioma forem colocadas em pastas, por exemplo, site.com/de/ e site.com/fr/, todo o projeto permanecerá dentro de um único domínio. Isso simplifica a coleta de dados: em vez de fazer solicitações separadas para vários recursos, você pode trabalhar com uma única Propriedade de Domínio no Google Search Console.

Em vez de 10 consultas separadas, você pode fazer uma grande exportação, usando filtragem para contornar o limite de 50.000 linhas. Isso economiza cotas da API do Google e reduz a carga na rede.

Grandes exportações ainda precisam ser divididas em segmentos. Mas a própria arquitetura torna-se mais simples: menos pontos de conexão, menos solicitações e menor carga na API.

Como a API nos fornece um fluxo contínuo de URLs, o próprio script deve atribuir marcadores de país às linhas. Isso é feito usando expressões regulares (RegEx).

Usando a biblioteca Pandas, podemos extrair o marcador de idioma diretamente da URL:

df['language_market'] = df['page'].str.extract(r'\.com/([a-z]{2})/')
# Exception handling: if RegEx returns NaN, this is the main version of the site
df['language_market'].fillna('en', inplace=True)

df['language_market'] = df['page'].str.extract(r'\.com/([a-z]{2})/')
# Exception handling: if RegEx returns NaN, this is the main version of the site
df['language_market'].fillna('en', inplace=True)

Isso permite extrair o marcador de de uma URL como site.com/de/product e usá-lo para análises posteriores.

A principal limitação dessa abordagem é a sua dependência da estrutura da URL. A expressão regular deve corresponder exatamente às regras usadas para construir as versões de idioma. Se algumas páginas usarem um padrão diferente, como site.com/category-de/product, essas URLs podem ser classificadas incorretamente ou nem sequer entrar no segmento necessário.

É por isso que, antes de configurar o RegEx, é importante verificar todos os padrões possíveis de URL de idioma e tratar as exceções separadamente.

Transformação de dados e cálculo de métricas em Pandas

Depois de coletar e normalizar os dados, eles precisam ser combinados e preparados para análise. O Pandas é conveniente para isso: a biblioteca permite trabalhar com grandes tabelas, combinar fontes e calcular métricas tanto no nível da linha quanto do grupo.

Combinando dados do GSC e GA4 por URL

O Google Search Console exibe métricas de pesquisa — impressões, cliques, CTR e posições. O GA4 complementa essas com métricas comportamentais e de negócios, como sessões e conversões.

Para obter uma imagem mais completa do desempenho do tráfego de SEO, os dados do GSC e do GA4 podem ser combinados usando uma chave comum — a URL normalizada da página de destino.

No Pandas, isso é feito juntando as tabelas usando uma chave comum, a URL normalizada:

import pandas as pd

# df_gsc — export from Search Console
# df_ga4 — export from GA4 (Sessions, Conversions)

# Join the data by landing page (Left Join so that pages without traffic are not lost)
merged_df = pd.merge(df_gsc, df_ga4, how='left', left_on='landing_page', right_on='page_path')

# We can now calculate the conversion rate of a specific SEO cluster:
merged_df['seo_conversion_rate'] = (merged_df['conversions'] / merged_df['clicks']) * 100

import pandas as pd

# df_gsc — export from Search Console
# df_ga4 — export from GA4 (Sessions, Conversions)

# Join the data by landing page (Left Join so that pages without traffic are not lost)
merged_df = pd.merge(df_gsc, df_ga4, how='left', left_on='landing_page', right_on='page_path')

# We can now calculate the conversion rate of a specific SEO cluster:
merged_df['seo_conversion_rate'] = (merged_df['conversions'] / merged_df['clicks']) * 100

Cálculo correto de CTR e posição média

Ao combinar dados de várias versões de idioma, você não pode calcular o CTR e a posição média simplesmente usando uma média aritmética. Isso distorce o resultado porque não leva em conta os diferentes volumes de impressões.

Por exemplo:

• Subdomínio francês: 2 cliques em 4 impressões, CTR = 50%;

• Subdomínio alemão: 20 cliques em 1.000 impressões, CTR = 2%.

Se você simplesmente tirar a média dos valores de CTR, obterá:

(50% + 2%) / 2 = 26%

Mas o CTR real nos dois subdomínios é:

22 cliques / 1004 impressões = 2,19%

Portanto, ao agregar dados de diferentes localizações, as métricas precisam ser recalculadas a partir dos valores subjacentes:

• O CTR é calculado como a razão entre o total de cliques e o total de impressões.

• A posição média deve ser ponderada pelas impressões: a posição de cada linha é multiplicada pelo número de impressões, e a soma desses valores é então dividida pelas impressões totais.

No Pandas, isso pode ser implementado da seguinte forma:

# Group the data by search query across all countries
def weighted_metrics(x):
    # Weighted average position = Sum (Position * Impressions) / Sum (Impressions)
    weighted_pos = (x['position'] * x['impressions']).sum() / x['impressions'].sum()
    # Actual CTR
    real_ctr = (x['clicks'].sum() / x['impressions'].sum()) * 100
    
    return pd.Series({
        'total_clicks': x['clicks'].sum(),
        'total_impressions': x['impressions'].sum(),
        'weighted_position': weighted_pos,
        'real_ctr': real_ctr
    })

# Apply the function to the grouped dataframe
final_cluster_data = merged_df.groupby('query').apply(weighted_metrics)

# Group the data by search query across all countries
def weighted_metrics(x):
    # Weighted average position = Sum (Position * Impressions) / Sum (Impressions)
    weighted_pos = (x['position'] * x['impressions']).sum() / x['impressions'].sum()
    # Actual CTR
    real_ctr = (x['clicks'].sum() / x['impressions'].sum()) * 100
    
    return pd.Series({
        'total_clicks': x['clicks'].sum(),
        'total_impressions': x['impressions'].sum(),
        'weighted_position': weighted_pos,
        'real_ctr': real_ctr
    })

# Apply the function to the grouped dataframe
final_cluster_data = merged_df.groupby('query').apply(weighted_metrics)

Automatizando o monitoramento de hreflang e canibalização

Um data warehouse dedicado pode ser usado não apenas para relatórios, mas também para detectar problemas técnicos de SEO automaticamente. Dois tipos de problemas são especialmente importantes para projetos multilíngues: relações de localização rompidas e competição interna entre várias páginas pela mesma demanda de pesquisa.

Monitoramento automatizado de hreflang

A otimização técnica de SEO para projetos internacionais depende da consistência e bidirecionalidade das tags de localização. A tag hreflang funciona como um sistema estrito de referência cruzada bidirecional. Se, por exemplo, uma página francesa aponta para uma página alemã como alternativa, a página alemã deve conter um link recíproco. Romper essa cadeia quebra todo o cluster aos olhos do Google.

Em um projeto grande, verificar manualmente esses links é impossível, portanto, o monitoramento deve ser baseado na comparação de pelo menos duas fontes de dados:

• Screaming Frog. Execute o rastreador de forma programada. Ele verifica a presença real de tags no código HTML e valida códigos de idioma (ISO 639-1) e códigos de país (ISO 3166-1 Alpha 2). Os resultados são exportados para um banco de dados.

• API do GSC. A API do Search Console fornece um relatório de indexação e mostra como o Google interpretou essas relações durante o seu rastreamento mais recente.

Os resultados do rastreamento e os dados do Google podem ser armazenados no mesmo banco de dados e depois comparados usando SQL. Por exemplo, um FULL OUTER JOIN pode identificar bugs críticos nos dados agregados: páginas que tecnicamente possuem tags corretas em seu código, mas foram ignoradas pelo mecanismo de pesquisa.

Pode haver muitos motivos para isso. Uma possibilidade é a renderização no lado do cliente: frameworks JavaScript (React, Vue) demoram muito para renderizar as tags em <head>, ou as métricas de desempenho (Core Web Vitals) são tão ruins que o Googlebot expira antes de conseguir ler o hreflang. A automação detecta esses problemas antes que o tráfego comece a cair.

Canibalização de tráfego e localização de URLs conflitantes

O segundo problema multilíngue é a competição interna. A canibalização ocorre quando um mecanismo de pesquisa fica confuso sobre a relevância e começa a classificar, por exemplo, a versão em inglês de uma página para uma consulta vinda da Alemanha, embora você tenha uma página de destino dedicada em alemão.

Essas sobreposições são difíceis de analisar em escala na interface padrão do GSC. Se os dados brutos forem armazenados no BigQuery, a canibalização potencial pode ser detectada automaticamente usando SQL.

O algoritmo de detecção de canibalização é o seguinte:

1. Agrupe os dados por dois parâmetros: query e country.

2. Conte o número de URLs exclusivas (COUNT(DISTINCT page)) que recebem impressões para essa combinação.

3. Filtre os resultados usando HAVING count > 1.

Se várias páginas receberem impressões para a mesma combinação de query + country, isso é um sinal de um potencial conflito de relevância.

Os dados do GSC podem ser complementados verificando os resultados reais de pesquisa para as regiões relevantes. Isso é especialmente útil quando a análise já identificou uma anomalia, mas os números por si só não deixam claro o que exatamente o usuário vê e qual versão da página o Google exibe em um determinado país.

Abordamos métodos para coletar SERPs automaticamente em um artigo separado. E quando você precisar verificar manualmente consultas e localizações individuais em diferentes ambientes regionais, poderá usar um navegador antidetecção como o Octo Browser.

Artigo relacionado

Raspagem da web dos resultados da Pesquisa Google: tutorial

Como o Octo Browser complementa a análise de SEO

O GSC e o BigQuery são adequados para encontrar problemas em grandes volumes de dados. Eles podem ajudá-lo a perceber, por exemplo, que uma página em alemão começou a perder impressões, que a localização errada se classifica para consultas de um determinado país ou que várias URLs estão competindo entre si.

Mas depois de encontrar esse problema, geralmente surge a pergunta: o que o usuário realmente vê nos resultados da pesquisa?

Os dados do GSC ajudam a identificar uma anomalia e entender sua escala. Para diagnosticar um caso específico, é útil olhar para os resultados de pesquisa da região necessária e verificar como o site realmente se comporta.

É aí que o Octo Browser entra. Para diferentes países, você pode criar perfis separados, conectar proxies com a geolocalização necessária e realizar verificações em sessões de navegador isoladas. Isso é conveniente quando você trabalha regularmente com várias geolocalizações e não deseja misturar cookies, histórico e outros dados entre as verificações.

Por exemplo, nosso script detecta que a URL em inglês está recebendo impressões para consultas da Alemanha, embora o site tenha uma versão completa em alemão em /de/. Isso não significa necessariamente que o problema esteja definitivamente relacionado à localização. Primeiro, vale a pena verificar o que está acontecendo nos resultados reais de pesquisa.

Abra um perfil do Octo com um proxy alemão e verifique qual URL o Google exibe para a consulta desejada. Ao mesmo tempo, você pode verificar se a versão correta do site é aberta, se há um redirecionamento automático para outro idioma e se o conteúdo da página corresponde à região selecionada.

Você pode usar o mesmo método para verificar seletivamente:

• a exibição da versão de idioma incorreta na SERP;

• diferenças nos resultados de pesquisa em várias regiões;

• o funcionamento de redirecionamentos regionais;

• a localização de conteúdo, preços e outros elementos da página;

• alterações após a correção de hreflang, canonical ou links internos.

Desta forma, a API do GSC e o BigQuery ajudam a identificar casos suspeitos em todo o projeto, enquanto o Octo Browser ajuda a investigar anomalias individuais usando as geolocalizações necessárias em ambientes isolados.

Conclusão

Mover a análise de SEO das interfaces web para um sistema personalizado de coleta e armazenamento de dados é um upgrade para um nível totalmente novo de gerenciamento de projetos.

No início, tal arquitetura é tecnicamente exigente: você precisa configurar autorização, tratamento de erros, normalização de dados, exportações regulares e gerenciamento de processos. Mas como resultado, você obtém um sistema que escala com o projeto e não depende das limitações das interfaces web.

Em vez de coletar relatórios manualmente, você terá um único banco de dados com histórico onde poderá analisar todas as versões de idioma, recalcular métricas corretamente, identificar problemas técnicos e construir os recortes de dados de que precisa sem perder a granularidade.