Google Search Console API: como automatizar dados SEO (2026)

Exportar CSV à mão não escala quando gere dez ou vinte propriedades GSC. A Search Console API permite puxar cliques, impressões e queries por código — desde que aceite OAuth, quotas e os limites do que a API não expõe (totais agregados do cartão Page indexing, indexação em massa).

A Google Search Console API automatiza a extracção de Search Analytics (queries, páginas, dispositivo, país) e endpoints de inspecção limitados. Use-a para relatórios recorrentes e alertas; não substitui estratégia SEO nem força indexação em dezenas de URLs.

Quando automatizar (e quando ficar na UI)

• Automatize se precisa do mesmo corte de dados toda semana (top queries, páginas com impressões e CTR baixo, comparativo 28 vs 28 dias) para vários clientes.
• Fique na UI para validações pontuais, Rich Results, um único URL Inspection ou quando ainda está a definir o template de relatórios GSC para clientes.
• Híbrido: API alimenta o armazém de dados; analista interpreta — alinhado com reporting GSC multi-cliente no produto.

Interface GSC vs Search Console API

Se o problema principal é «Crawled – currently not indexed», a API ajuda a cruzar URLs com impressões zero — mas a correcção continua editorial. Veja o guia Crawled – currently not indexed.

Pré-requisitos no Google Cloud

1. Projecto Google Cloud (billing activo se usar outras APIs; Search Console API em si não factura por chamada).
2. Activar Google Search Console API (searchconsole.googleapis.com).
3. Credenciais OAuth 2.0 tipo Desktop app → descarregar JSON (no guia abaixo: credenciais.json).
4. Utilizador Google com acesso de proprietário ou utilizador completo à propriedade GSC alvo.

Dependências Python recomendadas:

pip install google-auth-oauthlib google-auth-httplib2 google-api-python-client

Opcional com gcloud CLI:

gcloud services enable searchconsole.googleapis.com

Script Python: OAuth + Search Analytics

O exemplo usa scope readonly, ficheiro de secrets credenciais.json e grava token.json para refresh. Ajuste PROPRIEDADE para URL-prefix (https://www.exemplo.pt/) ou domínio (sc-domain:exemplo.pt).

from google.oauth2.credentials import Credentials
from google_auth_oauthlib.flow import InstalledAppFlow
from google.auth.transport.requests import Request
from googleapiclient.discovery import build
import os.path

AMBITOS = ['https://www.googleapis.com/auth/webmasters.readonly']
PROPRIEDADE = 'https://www.exemplo.pt/'

def credenciais_gsc():
    creds = None
    if os.path.exists('token.json'):
        creds = Credentials.from_authorized_user_file('token.json', AMBITOS)
    if not creds or not creds.valid:
        if creds and creds.expired and creds.refresh_token:
            creds.refresh(Request())
        else:
            flow = InstalledAppFlow.from_client_secrets_file('credenciais.json', AMBITOS)
            creds = flow.run_local_server(port=0)
        with open('token.json', 'w', encoding='utf-8') as token:
            token.write(creds.to_json())
    return creds

def listar_propriedades():
    servico = build('searchconsole', 'v1', credentials=credenciais_gsc())
    resposta = servico.sites().list().execute()
    for entrada in resposta.get('siteEntry', []):
        print(entrada['siteUrl'], entrada.get('permissionLevel'))

def relatorio_queries_paginas():
    servico = build('searchconsole', 'v1', credentials=credenciais_gsc())
    corpo = {
        'startDate': '2026-09-01',
        'endDate': '2026-09-30',
        'dimensions': ['query', 'page'],
        'rowLimit': 1000,
    }
    resposta = servico.searchanalytics().query(siteUrl=PROPRIEDADE, body=corpo).execute()
    for linha in resposta.get('rows', []):
        query, pagina = linha['keys']
        print(
            query,
            pagina,
            linha.get('clicks', 0),
            linha.get('impressions', 0),
            round(linha.get('ctr', 0) * 100, 2),
            round(linha.get('position', 0), 1),
        )

if __name__ == '__main__':
    listar_propriedades()
    relatorio_queries_paginas()

Na primeira execução abre-se o browser para consentimento OAuth. Guarde token.json fora do repositório git — trate-o como password.

Do JSON bruto a acções de SEO

Pipeline típico de agência depois da query:

• Filtrar linhas com impressões ≥ N e CTR abaixo do benchmark da posição → fila de reescrita de title/meta (ver CTR no GSC: melhorar títulos).
• Agregar por página para encontrar canibalização ou URLs órfãs.
• Comparar semana actual vs anterior no seu data warehouse — a API não envia email; isso é o seu cron ou ferramenta SaaS.

Quotas, erros 403 e URL Inspection

Search Analytics tem limites de linhas por pedido e quotas diárias por projecto. Erros 403 quotaExceeded pedem backoff e cache — não scripts a correr de minuto a minuto. A URL Inspection API é útil para amostragem automatizada (estado de indexação de URLs prioritárias), não para inspeccionar centenas de URLs legacy num único dia.

Pedido de indexação: a API pode, após inspecção, permitir submissão pontual — não há substituto para qualidade, sitemap e links internos. Não confunda automatizar dados com «forçar» o índice.

Multi-cliente: porque scripts locais falham cedo

Cada cliente precisa de consentimento OAuth, rotação segura de refresh tokens e separação de dados por organização — requisitos que explicam porque ferramentas como o DENVORA SEO centralizam sync GSC em vez de partilhar um token.json por Slack. Se o objectivo é entrega mensal, combine API (extração) com o formato do guia relatórios GSC para clientes e a página Relatórios Google Search Console.