Como usar a API do Google Search Console?

Q: Como usar a API do Google Search Console?

Configure um projeto no Cloud, ative a API, autorize com OAuth e consulte dados de desempenho, inspeção de URL e sitemaps. Veja os passos e as cotas.

Crie um projeto no console do Google Cloud, ative a Google Search Console API, crie credenciais OAuth 2.0 e faça login com uma conta Google que tenha acesso à propriedade. Depois, você pode enviar solicitações a quatro recursos: Search Analytics, para cliques, impressões, CTR e posição; URL Inspection, para o status de indexação; Sitemaps; e Sites. Chaves de API sozinhas não funcionam: toda chamada exige um token OAuth, e as cotas limitam quanto você pode solicitar.

O que a API cobre e o que ela não cobre

Recurso	Métodos	Use para
Search Analytics	`query`	Linhas de desempenho por consulta, página, país, dispositivo, aparência na pesquisa, data ou hora
URL Inspection	`index.inspect`	A versão indexada de uma URL: cobertura, último rastreamento, canônicas
Sitemaps	`list`, `get`, `submit`, `delete`	Gerenciar os sitemaps enviados por uma propriedade
Sites	`list`, `get`, `add`, `delete`	As propriedades da conta conectada

Isso é toda a API. Links, Estatísticas de rastreamento, o relatório de indexação de páginas e o relatório de Core Web Vitals não têm endpoint, então continuam disponíveis apenas na interface do Search Console. A URL Inspection mostra o que está no índice do Google, não um teste ao vivo da página.

Configure o acesso

No console do Google Cloud, crie ou escolha um projeto.
Ative a Google Search Console API nesse projeto.
Configure a tela de consentimento OAuth e crie um ID de cliente OAuth.
Solicite um escopo: https://www.googleapis.com/auth/webmasters.readonly para leitura, ou https://www.googleapis.com/auth/webmasters para também enviar ou excluir sitemaps.
Faça login com uma conta que tenha permissão na propriedade. Para ler dados de desempenho, é preciso ter pelo menos acesso de leitura; a API vê exatamente o que essa conta vê.

Sua primeira consulta ao Search Analytics

POST https://www.googleapis.com/webmasters/v3/sites/sc-domain%3Aexample.com/searchAnalytics/query
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "startDate": "2026-09-01",
  "endDate": "2026-09-30",
  "dimensions": ["query", "page"],
  "type": "web",
  "rowLimit": 25000,
  "startRow": 0
}

O site vai no caminho, codificado como URL: sc-domain:example.com para uma propriedade de domínio, ou o prefixo exato com a barra final, como https://www.example.com/, para uma propriedade de prefixo de URL. Os campos mais importantes:

Datas são inclusivas e usam o fuso horário do Pacífico (Pacific Time).
type é web por padrão; image, video, news, googleNews e discover são os outros. Cada um exige uma solicitação própria.
Filtros vão em dimensionFilterGroups, com operadores que vão de equals e contains a includingRegex e excludingRegex (sintaxe RE2).
rowLimit vai de 1 a 25.000 (padrão: 1.000); startRow percorre o restante.
dataState é final por padrão; all inclui dias recentes ainda não consolidados e hourly_all funciona com a dimensão hour.

Cada linha retorna keys, clicks, impressions, ctr (de 0 a 1) e position, ordenadas por cliques, a menos que você agrupe por data.

Os limites que moldam o seu código

50.000 linhas por dia por tipo de pesquisa. Percorra os resultados com startRow em passos de 25.000 e pare quando a resposta vier vazia. Para obter o máximo de dados, consulte um dia por vez.
Cota de carga. Agrupar ou filtrar por página e consulta ao mesmo tempo é a solicitação mais cara, e intervalos de datas longos custam mais que os curtos. Se você exceder a cota de curto prazo, o Google pede que você aguarde 15 minutos.
Taxas de solicitação. 1.200 consultas por minuto por site e por usuário; 40.000 por minuto e 30.000.000 por dia por projeto.
Cota da URL Inspection. 2.000 inspeções por dia e 600 por minuto para cada propriedade.
16 meses de histórico, e os dados costumam ficar disponíveis de dois a três dias após o fim do dia.
As linhas não somam os totais. Consultas raras ficam de fora das linhas por consulta, e agrupar por página conta as impressões de forma diferente de agrupar por propriedade; por isso, leia os totais em uma solicitação sem a dimensão de consulta.

Erros comuns

Usar http:// quando a propriedade é https://, ou omitir a barra final, gera um erro de permissão mesmo quando a conta tem acesso.
Pedir, na URL Inspection, uma URL fora da propriedade é rejeitado: a URL precisa estar dentro do siteUrl informado.
Um mês agrupado por consulta e página em uma única chamada retorna apenas as primeiras linhas. Solicitações diárias retornam mais.

Como o AutoPSEO ajuda

Se você prefere não manter OAuth e paginação, o AutoPSEO se conecta por meio do login do Google e expõe os mesmos dados pela própria REST API em /v1 (com um documento OpenAPI 3.1) e por um servidor MCP, autorizados por uma chave de API de Conta → Chaves de API. Há chaves somente leitura, o endpoint de search analytics retorna até 5.000 linhas por chamada, e as ferramentas de URL Inspection do app controlam por você a cota de 2.000 por dia do Google. Veja MCP e chaves de API. Para manter dados além de 16 meses sem escrever um pipeline, consulte por quanto tempo o Search Console guarda os dados.

Fontes: referência da API, método query do Search Analytics, limites de uso, como obter todos os seus dados e guia de autorização do Google.