CommunityPesquisa e Análise de Dadosgithub.com

Google Search Console API

Trabalhe com a API do Google Search Console (searchconsole v1 / webmasters v3) — Consultas de Análise de Pesquisa, Inspeção de URL, Sitemaps e Sites — mantendo-se dentro das cotas. Use quando solicitado a 'extrair dados do Search Console', 'exportar dados de desempenho do GSC', 'consultar cliques/impressões/CTR/posição por página ou consulta', 'construir um pipeline ou dashboard do GSC', 'obter mais de 1.000 / 25.000 linhas', 'inspecionar URLs / verificar status do índice via API', 'inspeção em lote de URLs', 'enviar um sitemap via API', 'listar propriedades do Search Console', configurar OAuth ou uma conta de serviço para o Search Console, ou depurar erros de 'quota excedida', 403 ou 'Usuário não tem permissão suficiente' da API do Search Console.

O que é Google Search Console API?

Esta skill fornece acesso programático completo ao Google Search Console, cobrindo a API de Análise de Pesquisa (desempenho), Inspeção de URL, Sitemaps e listagem de propriedades (Sites). Seu principal objetivo é ajudar desenvolvedores e profissionais de SEO a extrair dados de desempenho (cliques, impressões, CTR, posição), verificar o status de indexação de URLs e gerenciar sitemaps de forma eficiente, evitando os limites de cota da API. A skill aborda os desafios mais comuns, como lidar com erros 'quotaExceeded', garantir a integridade dos dados ao paginar resultados de até 25.000 linhas e compreender as nuances das métricas (CTR agregado, posição ponderada por impressão) e dos identificadores de propriedade (domínio vs. prefixo de URL). Ela suporta autenticação via OAuth 2.0 (contas de serviço para tarefas automatizadas) e contas de usuário, com instruções detalhadas de configuração para Python, Node.js e outras linguagens. Além disso, inclui práticas recomendadas como consultar um dia de cada vez, nunca religar o histórico finalizado e usar filtros e agregações corretamente para evitar a perda de dados. A skill também cobre a Inspeção de URL (2.000 consultas/dia/propriedade), a diferença entre as cotas de curto prazo (QPM) e longo prazo (carga), e um script auxiliar para linha de comando.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/nimajafari/google-search-console-api-skill/tree/main/skills/google-search-console-api

Installed? Explore more Pesquisa e Análise de Dados skills: affaan-m/uspto-database, affaan-m/scholar-evaluation, affaan-m/literature-review · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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çoMétodoHTTPEscopo (mín.)
Search Analyticssearchanalytics.queryPOST /webmasters/v3/sites/{siteUrl}/searchAnalytics/querywebmasters.readonly
Inspeção de URLurlInspection.index.inspectPOST /v1/urlInspection/index:inspectwebmasters.readonly
Sitemapslist / getGET /webmasters/v3/sites/{siteUrl}/sitemaps[/{feedpath}]webmasters.readonly
Sitemapssubmit / deletePUT / DELETE …/sitemaps/{feedpath}webmasters
Siteslist / getGET /webmasters/v3/sites[/{siteUrl}]webmasters.readonly
Sitesadd / deletePUT / 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, siteUrl e feedpath devem 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.list e use um siteUrl exatamente como retornado. siteUnverifiedUser nã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 page ou query (ambos juntos é o mais caro),
    • o comprimento do intervalo de datas (6 meses ≫ 1 dia),
    • consultar novamente dados que você já possui.
  • 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)

  1. 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.
  2. Consulte um dia de cada vez (startDate == endDate), uma vez por dia, para cada type que 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á.
  3. Paginar pelos resultados: rowLimit máximo de 25.000 (padrão 1.000), incremente startRow em 25.000 até que uma página retorne menos linhas do que o solicitado ou 0 linhas.
  4. 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 page e/ou query descarta 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ões page/query.
  • Os totais diferem por agregação: byProperty (desduplicado por propriedade) vs byPage (por URL canônica). Se você agrupar ou filtrar por page, byProperty não é permitido — use auto.
  • 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}; operadores equals (padrão, diferencia maiúsculas de minúsculas para página/consulta), notEquals, contains, notContains, includingRegex, excludingRegex (RE2). Grupos são combinados com AND; apenas groupType: "and" é suportado.
  • dimensionFilterGroups[].filterLists[]: correspondência exata de vários valores para country / device ({"dimension":"country","expressions":["usa","can"]}). Não é possível filtrar a mesma dimensão em filters e filterLists.
  • aggregationType: auto (padrão), byPage, byProperty (não para discover/googleNews), byNewsShowcasePanel.
  • dataState: final (padrão), all (inclui dados novos, ainda não finais), hourly_all (necessário para a dimensão hour; ~10 dias disponíveis). O metadata.firstIncompleteDate / firstIncompleteHour da resposta marca onde os números ainda podem mudar.

Armadilhas

  • A aparência de pesquisa é de dois passos: consulte com searchAppearance como a única dimensão para listar os tipos, em seguida filtre searchAppearance equals <TYPE> e adicione outras dimensões — uma consulta por tipo.
  • brandedClassification (BRANDED / NON_BRANDED): apenas equals; não pode ser combinado com um filtro query na 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 startRow fora 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.
  • rows está 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.
  • inspectionUrl deve estar em siteUrl.
  • Leia indexStatusResult: verdict (PASS = válido, NEUTRAL = excluído, FAIL = erro), coverageState (a string legível, ex. "Submetida e indexada"), robotsTxtState, indexingState, pageFetchState, lastCrawlTime, googleCanonical vs userCanonical, crawledAs.
  • O sinal em massa mais útil é googleCanonical != userCanonical (o Google escolheu uma canônica diferente).
  • mobileUsabilityResult está obsoleto. ampResult / richResultsResult estã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.

  1. Crie/escolha um projeto do Google Cloud → ative a API Google Search Console.
  2. 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.
  3. Use uma biblioteca de cliente (recomendado) — ex. Python google-api-python-client com build("searchconsole", "v1", credentials=creds), Node googleapis com google.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.

SintomaCausaAção
401 authError / expiredtoken inválido/expiradoatualize 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 propriedadesites.list, use o siteUrl exato; adicione a conta de serviço no Search Console
403 accessNotConfiguredAPI não ativada no projetoative a API Search Console
403/429 rateLimitExceeded, userRateLimitExceededQPS/QPMbackoff exponencial com jitter
403/429 quotaExceeded (Search Analytics)cota de cargaaguarde 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 / badRequestenum inválido, ordem de data, filters/filterLists misturados na mesma dimensão, byProperty com páginacorrija a solicitação; não tente novamente
500 / 503 backendErrortransitóriobackoff 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.

Habilidades Relacionadas