O que Google Search Console API faz?
A API do Search Console é acesso programático para a maior parte do Google Search Console: o relatório de Desempenho (Search Analytics), Inspeção de URL, Sitemaps e a lista de propriedades (Sites). É uma API REST/JSON. Cada chamada precisa de OAuth 2.0 e de um usuário (ou conta de serviço) com permissão no Search Console para a propriedade.
A parte difícil não é fazer uma chamada. É obter dados completos e corretos sem estourar a cota. A maior parte desta skill é sobre isso.
Quando usar esta skill
- Extrair dados de Desempenho (cliques, impressões, CTR, posição) para análise, dashboards, armazenamento ou investigações de SEO.
- Verificar status de indexação, canônica escolhida, estado de robots/noindex ou validade de rich results para URLs em escala.
- Listar propriedades e permissões, listar ou enviar sitemaps.
- Projetar um trabalho de sincronização agendado, ou corrigir um que atinge
quotaExceeded, perde linhas ou retorna números que não correspondem à interface do usuário.
Não cobertos por esta API: o relatório de indexação de páginas (cobertura), Links, Core Web Vitals, Estatísticas de rastreamento, Ações manuais, remoções e o botão "Solicitar indexação". Para Core Web Vitals reais, use a API CrUX; para dados brutos de Desempenho em massa em sites grandes, use a exportação de dados em massa para BigQuery do Search Console; a API de Indexação separada suporta apenas páginas JobPosting / BroadcastEvent.
Os quatro serviços
| Serviço | Método | HTTP | Escopo (mín.) |
|---|---|---|---|
| Search Analytics | searchanalytics.query | POST /webmasters/v3/sites/{siteUrl}/searchAnalytics/query | webmasters.readonly |
| Inspeção de URL | urlInspection.index.inspect | POST /v1/urlInspection/index:inspect | webmasters.readonly |
| Sitemaps | list / get | GET /webmasters/v3/sites/{siteUrl}/sitemaps[/{feedpath}] | webmasters.readonly |
| Sitemaps | submit / delete | PUT / DELETE …/sitemaps/{feedpath} | webmasters |
| Sites | list / get | GET /webmasters/v3/sites[/{siteUrl}] | webmasters.readonly |
| Sites | add / delete | PUT / DELETE /webmasters/v3/sites/{siteUrl} | webmasters |
URL raiz: https://searchconsole.googleapis.com/ (documento de descoberta atual, serviço searchconsole v1). Os caminhos mais antigos https://www.googleapis.com/webmasters/v3/... ainda aparecem na documentação do Google e ainda funcionam para os recursos webmasters/v3.
Escopos: https://www.googleapis.com/auth/webmasters.readonly (somente leitura) e https://www.googleapis.com/auth/webmasters (leitura/gravação). Solicite somente leitura a menos que a tarefa realmente envie/exclua sitemaps ou adicione/remova sites.
Identificadores de propriedade (siteUrl) — a fonte nº 1 de 403/404
- Propriedade de domínio:
sc-domain:exemplo.com.br - Propriedade de prefixo de URL:
https://www.exemplo.com.br/— esquema, host e barra final devem corresponder exatamente ao que está no Search Console. - Em caminhos,
siteUrlefeedpathdevem ser completamente codificados em URL (https%3A%2F%2Fwww.exemplo.com.br%2F,sc-domain%3Aexemplo.com.br). As bibliotecas de cliente fazem isso por você; HTTP bruto não. - Sempre comece chamando
sites.liste use umsiteUrlexatamente como retornado.siteUnverifiedUsernão pode ler dados.
Cotas — leia antes de escrever qualquer loop
Detalhes completos e uma planilha de orçamento: references/LIMITS.md.
Search Analytics
- Limites de QPM: 1.200 QPM por site, 1.200 QPM por usuário, 40.000 QPM e 30.000.000 QPD por projeto. Exemplo: um usuário acessando 3 sites obtém 1.200 QPM combinados; dois usuários em um site compartilham 1.200 QPM.
- Cota de carga (a que realmente afeta): custo interno de uma consulta, rastreado em janelas de 10 minutos (curto prazo) e 1 dia (longo prazo). O custo aumenta com:
- agrupamento/filtragem por
pageouquery(ambos juntos é o mais caro), - o comprimento do intervalo de datas (6 meses ≫ 1 dia),
- consultar novamente dados que você já possui.
- agrupamento/filtragem por
- Exceder qualquer um deles retorna o mesmo erro
quotaExceeded. Curto prazo: aguarde 15 minutos e tente novamente. Se uma única consulta em uma janela de 10 minutos ainda falhar, você ultrapassou a cota de carga de longo prazo (diária) — reduza o custo; tentar novamente não ajudará até amanhã.
Inspeção de URL: 2.000 QPD e 600 QPM por site; 10.000.000 QPD e 15.000 QPM por projeto. 2.000 por dia por propriedade é o teto real — planeje amostragem, não planeje "inspecionar toda URL".
Todo o resto (sites, sitemaps): 20 QPS e 200 QPM por usuário; 100.000.000 QPD por projeto.
O lote não economiza cota: um lote de n chamadas conta como n solicitações. O lote apenas economiza sobrecarga HTTP. Uso atual: console do Google Cloud → APIs e Serviços → API Search Console → Cotas.
Search Analytics: obtendo dados completos e corretos
Esquema completo de solicitação/resposta e receitas: references/SEARCH-ANALYTICS.md.
O padrão recomendado (do guia "todos os seus dados" do Google)
- Verifique a atualização primeiro. Consulte os últimos ~10 dias agrupados apenas por
date— sem filtros, sem outras dimensões. Dias sem dados estão simplesmente ausentes. Os dados finais normalmente estão 2–3 dias atrasados. - Consulte um dia de cada vez (
startDate == endDate), uma vez por dia, para cadatypeque você precisar. Uma consulta diária de um dia não deve exceder sua cota diária; um intervalo de 16 meses agrupado por página+consulta excederá. - Paginar pelos resultados:
rowLimitmáximo de 25.000 (padrão 1.000), incrementestartRowem 25.000 até que uma página retorne menos linhas do que o solicitado ou 0 linhas. - Nunca religue o histórico finalizado. Armazene-o; busque apenas novos dias (além de buscar novamente os dias recentes não finalizados se você usar
dataState: "all").
POST https://searchconsole.googleapis.com/webmasters/v3/sites/sc-domain%3Aexemplo.com.br/searchAnalytics/query
{
"startDate": "2026-11-14",
"endDate": "2026-11-14",
"dimensions": ["page", "query", "country", "device"],
"type": "web",
"rowLimit": 25000,
"startRow": 0
}
Limites de dados rígidos que você deve explicar às partes interessadas
- A API retorna primeiras linhas, não todas as linhas: no máximo 50.000 linhas por dia por tipo de pesquisa (ordenadas por cliques), independentemente da paginação.
- Agrupar/filtrar por
pagee/ouquerydescarta alguns dados (para manter a computação limitada) e consultas raras anonimizadas nunca são retornadas. Portanto, soma das linhas < total da propriedade. Para totais precisos, consulte sem as dimensõespage/query. - Os totais diferem por agregação:
byProperty(desduplicado por propriedade) vsbyPage(por URL canônica). Se você agrupar ou filtrar porpage,byPropertynão é permitido — useauto. - As datas estão no Horário do Pacífico (
America/Los_Angeles), não em UTC. - A retenção de dados de desempenho no Search Console é de cerca de 16 meses. Persista-os se precisar de um histórico mais longo.
Matemática de métricas correta
- CTR de um grupo =
soma(cliques) / soma(impressões). Nunca faça a média das CTRs. - Posição de um grupo = ponderada por impressão:
soma(posição × impressões) / soma(impressões). Nunca faça a média das posições. positioné a posição superior média baseada em 1; menor é melhor.
Campos de solicitação principais (referência rápida)
dimensions:date,hour,query,page,country(ISO 3166-1 alpha-3, minúsculo nos resultados, ex.usa),device(DESKTOP/MOBILE/TABLET),searchAppearance,brandedClassification.type:web(padrão),image,video,news(aba Notícias),googleNews(news.google.com + aplicativo),discover,webMultimodal(Lens / Circle to Search / uploads de imagem).searchTypeé o alias obsoleto.dimensionFilterGroups[].filters[]:{dimension, operator, expression}; operadoresequals(padrão, diferencia maiúsculas de minúsculas para página/consulta),notEquals,contains,notContains,includingRegex,excludingRegex(RE2). Grupos são combinados com AND; apenasgroupType: "and"é suportado.dimensionFilterGroups[].filterLists[]: correspondência exata de vários valores paracountry/device({"dimension":"country","expressions":["usa","can"]}). Não é possível filtrar a mesma dimensão emfiltersefilterLists.aggregationType:auto(padrão),byPage,byProperty(não paradiscover/googleNews),byNewsShowcasePanel.dataState:final(padrão),all(inclui dados novos, ainda não finais),hourly_all(necessário para a dimensãohour; ~10 dias disponíveis). Ometadata.firstIncompleteDate/firstIncompleteHourda resposta marca onde os números ainda podem mudar.
Armadilhas
- A aparência de pesquisa é de dois passos: consulte com
searchAppearancecomo a única dimensão para listar os tipos, em seguida filtresearchAppearance equals <TYPE>e adicione outras dimensões — uma consulta por tipo. brandedClassification(BRANDED/NON_BRANDED): apenasequals; não pode ser combinado com um filtroqueryna mesma solicitação; dados de 2026-02-21 e apenas para propriedades de nível superior com volume suficiente.- Os resultados são ordenados por cliques decrescente, exceto quando agrupados por
date(data crescente). Empates são arbitrários — não confie na ordem para desduplicação. - Um
startRowfora do intervalo retorna 200 com zero linhas, não um erro. Os dados exatamente em um limite de 25.000 retornam uma próxima página vazia. rowsestá ausente (não[]) quando não há dados.
Inspeção de URL
Esquema completo, enums e uma tabela de triagem: references/URL-INSPECTION.md.
POST https://searchconsole.googleapis.com/v1/urlInspection/index:inspect
{ "inspectionUrl": "https://www.exemplo.com.br/pagina", "siteUrl": "sc-domain:exemplo.com.br", "languageCode": "pt-BR" }
- Relata apenas a versão indexada. Não pode testar uma URL ao vivo e não pode solicitar indexação.
inspectionUrldeve estar emsiteUrl.- Leia
indexStatusResult:verdict(PASS = válido, NEUTRAL = excluído, FAIL = erro),coverageState(a string legível, ex. "Submetida e indexada"),robotsTxtState,indexingState,pageFetchState,lastCrawlTime,googleCanonicalvsuserCanonical,crawledAs. - O sinal em massa mais útil é
googleCanonical != userCanonical(o Google escolheu uma canônica diferente). mobileUsabilityResultestá obsoleto.ampResult/richResultsResultestão ausentes quando não aplicáveis.- Orçamento: 2.000/dia/propriedade. Priorize uma amostra: principais páginas por cliques, modelos alterados recentemente, uma URL por modelo/padrão, URLs de novos sitemaps.
Sites e Sitemaps
Consulte references/SITES-AND-SITEMAPS.md. sites.list → siteEntry[] {siteUrl, permissionLevel} com siteOwner / siteFullUser / siteRestrictedUser / siteUnverifiedUser. sitemaps.list → sitemap[] com path, lastSubmitted, lastDownloaded, isPending, isSitemapsIndex, type, errors, warnings, contents[].submitted (contents[].indexed está obsoleto — não o relate). submit / delete não aceitam corpo e precisam do escopo de leitura/gravação. Estas são operações de gravação. Confirme com o usuário antes de chamá-las.
Autenticação e configuração
Passo a passo, além de linhas de instalação de biblioteca para cada linguagem: references/AUTH-AND-SETUP.md.
- Crie/escolha um projeto do Google Cloud → ative a API Google Search Console.
- Escolha uma credencial:
- Cliente OAuth instalado/desktop: para um humano executando scripts localmente; o usuário consente em um navegador e você armazena o token de atualização.
- Conta de serviço: para trabalhos não supervisionados. Em seguida, adicione o e-mail da conta de serviço como usuário na propriedade no Search Console (Configurações → Usuários e permissões). Restrito é suficiente para leituras; Proprietário/Completo é necessário para gravações. Sem esta etapa, toda chamada retorna 403.
- Chaves de API não são aceitas para esses recursos; OAuth 2.0 é o único protocolo suportado.
- Use uma biblioteca de cliente (recomendado) — ex. Python
google-api-python-clientcombuild("searchconsole", "v1", credentials=creds), Nodegoogleapiscomgoogle.searchconsole("v1").
from google.oauth2 import service_account
from googleapiclient.discovery import build
creds = service_account.Credentials.from_service_account_file(
"sa.json", scopes=["https://www.googleapis.com/auth/webmasters.readonly"])
gsc = build("searchconsole", "v1", credentials=creds, cache_discovery=False)
resp = gsc.searchanalytics().query(siteUrl="sc-domain:exemplo.com.br", body={
"startDate": "2026-11-14", "endDate": "2026-11-14",
"dimensions": ["page"], "rowLimit": 25000, "startRow": 0,
}).execute()
rows = resp.get("rows", []) # ausente quando vazio
Nunca imprima, registre ou confirme tokens, segredos de cliente ou chaves de conta de serviço.
Erros e novas tentativas
Mapa completo: references/ERRORS.md.
| Sintoma | Causa | Ação |
|---|---|---|
401 authError / expired | token inválido/expirado | atualize o token; verifique os escopos |
403 insufficientPermissions / "O usuário não tem permissão suficiente para o site" | formato siteUrl errado, ou o principal não é um usuário na propriedade | sites.list, use o siteUrl exato; adicione a conta de serviço no Search Console |
403 accessNotConfigured | API não ativada no projeto | ative a API Search Console |
403/429 rateLimitExceeded, userRateLimitExceeded | QPS/QPM | backoff exponencial com jitter |
403/429 quotaExceeded (Search Analytics) | cota de carga | aguarde 15 min uma vez; se uma única consulta ainda falhar → carga de longo prazo: reduza o intervalo de datas ou remova page/query, retome amanhã |
400 invalidParameter / badRequest | enum inválido, ordem de data, filters/filterLists misturados na mesma dimensão, byProperty com página | corrija a solicitação; não tente novamente |
500 / 503 backendError | transitório | backoff e tente novamente (limitado) |
Desempenho
references/BATCH-AND-PERFORMANCE.md: gzip (Accept-Encoding: gzip e um User-Agent contendo gzip), respostas parciais via fields= (ex. fields=rows(keys,clicks,impressions)), e lote HTTP (multipart/mixed, ≤ 1.000 chamadas, executado em qualquer ordem, cada chamada ainda conta contra a cota).
O script auxiliar
scripts/gsc.py é um CLI de arquivo único usando apenas a biblioteca padrão do Python 3.9+. Ele grava o progresso em stderr e os dados em stdout (JSONL por padrão, ou CSV/JSON). Ele pagina, processa limites de 50.000 linhas, e usa backoff exponencial nas chamadas da API. Para usar: python scripts/gsc.py --site 'sc-domain:exemplo.com.br' --start 2026-11-01 --end 2026-11-14 --dimensions page,query --type web.