Como verificar a posição de palavras-chave com a API da Google (guia 2026)

Tentar verificar a posição de uma palavra-chave com a API da Google é uma daquelas tarefas que parecem um problema resolvido até se pôr realmente mãos à obra. Não existe nenhum endpoint rankings.get(), e as duas API da Google a que as pessoas recorrem primeiro respondem, cada uma, a uma pergunta subtilmente diferente da que está a ser feita. A documentação do Search Analytics do Search Console é o ponto de partida certo, desde que perceba o que "posição" significa ali.

A Google tem uma API oficial de posicionamento de palavras-chave?

Não. A Google nunca lançou uma API que aceite uma palavra-chave e devolva a sua posição em tempo real no google.com. É intencional: a consulta automatizada da página de resultados é proibida pelos termos da Google, e a empresa não tem qualquer interesse comercial em fornecer infraestrutura de rank tracking.

Em vez disso, existem três vias parciais, cada uma com um limite rígido:

Como obtenho as posições das palavras-chave a partir da API do Search Console?

Consulte o endpoint searchAnalytics com a dimensão query e leia o campo position. São dados próprios, diretamente da Google, gratuitos e sem limite de palavras-chave: obtém todas as pesquisas para as quais o seu site recebeu impressões.

O pedido funcional, em Python:

from google.oauth2 import service_account
from googleapiclient.discovery import build

creds = service_account.Credentials.from_service_account_file(
    "service-account.json",
    scopes=["https://www.googleapis.com/auth/webmasters.readonly"],
)
service = build("searchconsole", "v1", credentials=creds)

response = service.searchanalytics().query(
    siteUrl="https://example.com/",
    body={
        "startDate": "2026-07-01",
        "endDate": "2026-07-31",
        "dimensions": ["query", "page"],
        "rowLimit": 25000,
    },
).execute()

for row in response.get("rows", []):
    query, page = row["keys"]
    print(f"{row['position']:.1f}  {query}  ->  {page}")

As três limitações que apanham toda a gente desprevenida

• A posição é uma média, não um ranking. Um valor de 7,4 não significa que está na posição 7: significa que as impressões se distribuíram por posições com uma média de 7,4, possivelmente entre 3 e 15 consoante os dispositivos e as localizações.
• Apenas o seu site. Não há forma de ver a posição de um concorrente. O Search Console é, por conceção, uma API limitada à propriedade.
• As palavras-chave sem impressões são invisíveis. Se estiver na posição 60 e ninguém tiver descido até lá, a pesquisa nem sequer aparece nos dados.

É esse terceiro ponto que, discretamente, arruína os relatórios. Uma palavra-chave para a qual ainda não conseguiu entrar nas primeiras páginas simplesmente não existe no Search Console, o que torna impossível medir a progressão da posição 60 para a posição 20 apenas com esta API.

Posso usar a Custom Search JSON API para verificar posicionamentos?

Tecnicamente sim, na prática não. A Custom Search JSON API exige que crie primeiro um Programmable Search Engine. Mesmo quando configurado para pesquisar toda a web, aplica o seu próprio ranking e as suas próprias restrições, pelo que a ordem que devolve não é a ordem que o google.com devolve.

Além disso, está limitada a 100 pesquisas por dia no nível gratuito, com a utilização paga faturada por cada mil pesquisas e um limite diário. Para um punhado de palavras-chave verificadas de vez em quando, é viável. Como ferramenta de rank tracking, produz números que parecem fidedignos mas estão discretamente errados, o que é pior do que não ter dados nenhuns.

E fazer scraping diretamente ao Google?

Não o faça. A consulta automatizada da Pesquisa Google sem autorização é contrária aos Termos de Utilização da Google e, em qualquer volume, provoca bloqueios de IP e barreiras de CAPTCHA. Para além da questão das políticas, a realidade técnica é desagradável: os resultados são personalizados, localizados e cada vez mais compostos com funcionalidades de IA, pelo que uma "posição" obtida por scraping varia consoante o centro de dados, a localização e a sessão, mesmo quando nada mudou no seu site.

Se precisa das posições dos concorrentes, uma SERP API comercial é a via simultaneamente legal ao abrigo dos acordos do próprio fornecedor e estável em termos operacionais. É uma rubrica paga, e esse custo é o preço honesto de dados que a Google não oferece. As empresas que precisam de construir e monitorizar este pipeline sem contratar internamente recorrem normalmente a um especialista; a nossa comparação das 10 melhores agências de análise de dados em França enumera fornecedores que configuram este tipo de relatórios.

O que deve realmente construir?

Para a maioria das equipas, a arquitetura mais pragmática é híbrida e tem este aspeto:

• A API do Search Console como espinha dorsal. Gratuita, com palavras-chave ilimitadas, dados próprios, e a única fonte que lhe diz para que pesquisas está realmente a obter impressões.
• Uma SERP API para um pequeno conjunto selecionado de palavras-chave. Os seus vinte ou trinta termos comercialmente críticos, verificados diariamente, incluindo as posições dos concorrentes.
• Uma camada de visibilidade na IA. Cada vez mais, a pergunta não é apenas "em que posição estou", mas "sou citado quando alguém pergunta a um assistente". As API clássicas de posicionamento não respondem a nada disto.

As equipas que preferem não arquitetar isto sozinhas entregam-no normalmente a um especialista; a nossa comparação das 10 melhores agências de SEO em França apresenta fornecedores que gerem este conjunto de relatórios para os seus clientes.

Este último ponto não é uma preocupação para o futuro. Quando uma resposta da IA resolve a pesquisa na própria interface, a posição dez e a posição três convergem para o mesmo resultado: nenhum clique. Monitorizar as citações a par das posições é precisamente aquilo para que foram concebidos o nosso servidor MCP para o Search Console e a nossa plataforma de visibilidade na IA, e a documentação explica a configuração do início ao fim.

Conclusão

Não existe uma API oficial da Google para posições de palavras-chave em tempo real: use a API do Search Console para os seus próprios dados médios, uma SERP API de terceiros para posições exatas e dos concorrentes, e deixe completamente de lado a Custom Search JSON API para o acompanhamento de posicionamentos. Construir sobre a opção errada é o erro mais comum nesta matéria, e produz um painel que é inexato com toda a confiança.

Se preferir não construir e manter esse pipeline por conta própria, a Sorank liga o seu Search Console e monitoriza as citações na IA num único local.