API do Search Console

TL;DR — A API do Search Console permite que você obtenha seus dados do Google Search Console com código, em vez de clicar na interface. É assim que você obtém mais do que a interface oferece — a exportação na interface chega a cerca de 1 000 linhas, enquanto a API oferece até 25 000 por solicitação. Você faz login com o Google (OAuth, não uma simples chave de API), e só recebe dados para sites que você verificou.

O que é a API do Search Console

O Search Console mostra como seu site se sai no Google — para quais consultas você ranqueia, quantos cliques e impressões você recebe, se suas páginas estão indexadas. A API oferece acesso programático a grande parte desses mesmos dados e desses mesmos controles, para que você possa alimentá-los em uma planilha, um painel ou um script que roda em um agendamento. No entanto, não é uma paridade total com a interface — algumas coisas (como testar uma URL ao vivo) só existem na interface, e ter acesso à API ou a automação não garante, por si só, indexação, ranqueamento, diagnóstico de tráfego ou visibilidade na busca com IA.

Há quatro partes:

1. API de Search Analytics — seus números do relatório de Performance (cliques, impressões, CTR, posição média), divididos por consulta, página, país, dispositivo e data.
2. API de URL Inspection — o status de indexação de uma única URL. Ela informa a versão atualmente no índice do Google; a ferramenta URL Inspection da interface também pode executar um teste ao vivo, o que a API não pode fazer.
3. API de Sitemaps — liste, envie ou exclua seus sitemaps.
4. API de Sites — liste, adicione ou remova as propriedades da sua conta.

Limite de propriedade de plataforma: o Search Console agora tem propriedades separadas para Instagram, TikTok, X e YouTube, mas a documentação atual de plataforma do Google descreve seus relatórios de interface e exportação de relatórios — não um identificador siteUrl ou contrato de suporte para esses endpoints legados. O fluxo de trabalho da API neste artigo, portanto, cobre apenas propriedades de sites. O LinkedIn não é uma propriedade de plataforma suportada.

Por que usar em vez da interface

O principal: linhas. Se você exportar o relatório de Performance da interface do Search Console, você obtém cerca de 1 000 linhas. A API retorna até 25 000 linhas por solicitação, e você pode paginar para obter mais. Se você tem um site com milhares de consultas ou páginas, a interface simplesmente não mostra a maior parte dos seus dados.

A outra razão é a automação. Uma vez que é uma chamada de API, você pode executá-la todas as manhãs, enviá-la para um painel ou alertar a si mesmo quando os cliques caírem.

A ressalva

Você só pode extrair dados de propriedades que você verificou no Search Console. Aponte a API para um site que você não possui e você não recebe nada — esse é o erro mais comum para iniciantes.

E a API não entrega tudo. Ela retorna as principais linhas, não a lista completa, e nunca mostra as consultas que o Google anonimiza por motivos de privacidade. Para um site grande que precisa de uma visão completa, a ferramenta mais adequada é a exportação de dados em massa para o BigQuery — explicada em detalhes na versão Advanced.

TL;DR — A API do Search Console são quatro APIs REST sob webmaster-tools/v1 — Search Analytics, URL Inspection, Sitemaps, Sites — todas OAuth 2,0, todas com escopo apenas para propriedades verificadas. O Search Analytics retorna 1–25 000 linhas por solicitação (padrão 1 000), mas “não garante retornar todas as linhas de dados, mas sim as principais”, então para completude em escala você avança para a exportação de dados em massa do BigQuery. O URL Inspection tem limite rígido de 2 000 QPD / 600 QPM por site — essa aritmética é o que limita o monitoramento de indexação em larga escala.

Este guia da API é limitado a propriedades de sites. Não presuma que os endpoints de Sites, Search Analytics, URL Inspection ou Sitemaps suportam propriedades de plataforma Instagram, TikTok, X ou YouTube até que o Google documente o identificador e o contrato de endpoint.

As quatro APIs em resumo

A própria definição do Google sobre o que a API faz: ela permite “view, add, or remove properties and sitemaps, run advanced queries for Google Search results data for the properties that you manage in Search Console, and test individual pages.” (tradução) «visualizar, adicionar ou remover propriedades e sitemaps, executar consultas avançadas sobre dados dos resultados da Pesquisa Google para as propriedades gerenciadas no Search Console e testar páginas individuais». Isso corresponde claramente aos quatro recursos, todos sob webmaster-tools/v1:

• Search Analytics API — o relatório de desempenho, programaticamente: cliques, impressões, CTR, posição por dimensão (consulta, página, país, dispositivo, aparência na pesquisa, data, hora).
• URL Inspection API — o status de indexação de uma única URL, o equivalente programático da ferramenta URL Inspection.
• Sitemaps API — listar, obter, enviar e excluir sitemaps.
• Sites API — listar, adicionar e remover propriedades verificadas.

Ela expõe muito do que você já usa na interface — o relatório de desempenho e a ferramenta URL Inspection — como endpoints que você pode automatizar. No entanto, não é um espelho 1:1: a API não garante paridade total com a interface (o teste ao vivo do URL Inspection, por exemplo, é exclusivo da interface — veja abaixo), e nem o acesso à API nem a automação por si só garantem indexação, ranqueamento, diagnóstico de tráfego ou visibilidade na pesquisa com IA.

Autenticação: OAuth 2,0, dois escopos, apenas propriedades verificadas

Não há chave de API. Cada chamada usa OAuth 2,0 — o Google afirma explicitamente que “all requests to the Google Search Console API must be authorized by an authenticated user.” (tradução) «todas as solicitações à API do Google Search Console devem ser autorizadas por um usuário autenticado». Você registra um aplicativo no Google Cloud, solicita um escopo e obtém um token de acesso de curta duração. Existem dois escopos:

• https://www.googleapis.com/auth/webmasters — leitura/gravação.
• https://www.googleapis.com/auth/webmasters.readonly — somente leitura.

Para automação servidor a servidor (um trabalho de relatório noturno, um monitor de indexação), você concede a uma conta de serviço acesso à propriedade e ignora o fluxo de consentimento interativo.

Para propriedades de site, dois formatos de identificador de propriedade também importam aqui: uma propriedade de prefixo de URL é passada como uma URL de propriedade completa (o próprio exemplo do Google é http://www.example.com/), e uma propriedade de domínio usa o formato sc-domain:example.com — você precisa passar o formato que corresponde à forma como a propriedade é verificada no Search Console. De qualquer forma, a conta de serviço (ou usuário) precisa ter acesso concedido a essa propriedade exata; não é uma forma de contornar a propriedade nem uma concessão geral para todas as propriedades da conta.

E a barreira que pega todo mundo: “You must have appropriate access (owner, full, read) to any Google Search Console account that you wish to access using the API.” (tradução) «você deve ter o acesso adequado — proprietário, total ou leitura — a qualquer conta do Google Search Console que queira acessar pela API». Chame a API para uma propriedade na qual você não está verificado e ela não retorna nada — não é necessariamente um erro visível, apenas dados vazios.

Search Analytics API — o relatório de desempenho, em escala

Comece pelo teto, não pela conveniência: a ressalva do próprio Google é que “The API is bounded by internal limitations of Search Console and does not guarantee to return all data rows but rather top ones.” (tradução) «a API está sujeita às limitações internas do Search Console e não garante o retorno de todas as linhas de dados, mas apenas das principais». A paginação amplia até onde você pode avançar nessa lista de linhas principais — ela não elimina o teto. Quando você precisa de todas as linhas, esse é o sinal para usar a exportação em massa do BigQuery (abaixo), não um rowLimit maior.

Dentro desse teto, esta ainda é a que a maioria procura. A razão pela qual ela supera a interface é o parâmetro rowLimit: “[Optional; Valid range is 1–25,000; Default is 1,000]” (tradução) «[Opcional; o intervalo válido é de 1 a 25 000; o padrão é 1 000]». A exportação da interface limita-se a cerca de 1 000 linhas; a API oferece até 25 000 por solicitação, e você pagina além disso com startRow. Em um site com uma cauda longa de consultas, essa é a diferença entre ver o topo dos seus dados e ver mais deles — ainda não todos.

Mais duas coisas moldam o que retorna. Primeiro, dataState controla a atualização: final (o padrão) retorna apenas dados finalizados, all inclui dados frescos, recém-coletados, e hourly_all fornece detalhamentos horários que são explicitamente parciais — os metadados da resposta sinalizam um first_incomplete_date ou first_incomplete_hour, e o Google observa que os valores após esse ponto ainda podem mudar. Segundo, as cotas do Search Analytics não são um número único: a página de limites de uso as divide em limites de carga (uma permissão baseada em recursos medida em blocos de 10 minutos e 1 dia — intervalos de datas mais amplos, mais dimensões e filtragem mais pesada consomem mais rápido) e os limites de taxa de solicitação QPS/QPM/QPD cobertos abaixo. Você pode atingir o teto de carga antes de atingir o teto de taxa de solicitação.

API de Inspeção de URL — e a cota que realmente limita você

A API de Inspeção de URL “view[s] the indexed, or indexable, status of the provided URL. Presently only the status of the version in the Google index is available; you cannot test the indexability of a live URL.” (tradução) «vê o status indexado, ou indexável, da URL fornecida. Atualmente, apenas o status da versão no índice do Google está disponível; você não pode testar a indexabilidade de uma URL ativa.» Essa última cláusula é um limite real de escopo, não um detalhe técnico: a ferramenta de Inspeção de URL da interface pode executar um teste ao vivo contra a página como ela existe agora; a API só pode relatar a versão que o Google já indexou. Use a API para construir monitoramento de cobertura de índice em muitas URLs — não como substituto para o teste ao vivo da interface.

Aqui é onde a matemática importa. Por site, você tem 2 000 consultas por dia e 600 por minuto. (Por projeto, o teto é muito maior — 10.000.000/dia e 15 000/minuto — mas o limite por site é o que pesa.) Se você quiser monitorar o status de indexação de um site com 50 000 URLs, não pode inspecionar todas em um dia; você faz lotes e agenda ao longo dos dias, ou prioriza. Poucos posts fazem essa aritmética, e é a maior restrição de planejamento para monitoramento de indexação em larga escala.

Em contraste, o Search Analytics é generoso — 1 200 QPM por site e por usuário — e os outros recursos (Sitemaps, Sites) ficam em 20 QPS / 200 QPM por usuário. A Inspeção de URL é o apertado.

APIs de Sitemaps e Sites

A API de Sitemaps é a camada de gerenciamento dos seus sitemaps: ela “submits a sitemap for a site,” (tradução) «envia um sitemap para um site»; “deletes a sitemap from this site,” (tradução) «exclui um sitemap deste site»; “retrieves information about a specific sitemap,” (tradução) «recupera informações sobre um sitemap específico»; e “lists the sitemaps-entries submitted for this site, or included in the sitemap index file.” (tradução) «lista as entradas de sitemaps enviadas para este site ou incluídas no arquivo de índice de sitemaps». O recurso de sitemap que ela retorna inclui campos como path, lastSubmitted, isPending, isSitemapsIndex, lastDownloaded, warnings, errors e um array contents — útil para auditar a saúde do sitemap em escala.

A API de Sites lista, adiciona e remove propriedades verificadas — útil se você gerencia muitas propriedades e quer provisioná-las ou auditá-las programaticamente.

Quando usar a exportação em massa para o BigQuery em vez disso

Para sites grandes, o modelo da API de 25 000 linhas por solicitação, apenas as principais linhas, torna-se um teto. A resposta do Google não é um quinto recurso de API que retorna o mesmo formato de dados — é um pipeline de exportação agendado separado: a exportação em massa de dados para o BigQuery. Pense na escolha como puxar vs. empurrar agendado, não “API A vs. API B.” O próprio enquadramento do Google: “Schedule a daily export of your Search Console performance data to BigQuery, where you can run complex queries over your data or export it to an external storage service. Using the bulk data export feature, you’ll see all the performance data available to Search Console for your property, with the exception of anonymized queries.” (tradução) «Agende uma exportação diária dos dados de desempenho do Search Console para o BigQuery, onde você pode executar consultas complexas sobre seus dados ou exportá-los para um serviço de armazenamento externo. Usando o recurso de exportação em massa, você verá todos os dados de desempenho disponíveis para o Search Console para sua propriedade, com exceção de consultas anonimizadas.»

Essa é a regra de decisão:

• Exportação da interface — ~1 000 linhas, olhada rápida única.
• API do Search Analytics — até 25 000 linhas/solicitação, paginação, scriptável; ótima para puxadas sob demanda moderadas e painéis.
• Exportação em massa do BigQuery — todos os dados de desempenho disponíveis, diariamente, sem limite de linhas; a ferramenta certa quando você tem dezenas de milhares de páginas ou consultas.

A única coisa que nenhum deles oferece são consultas anonimizadas — os termos que o Google oculta por privacidade. Essa é uma lacuna real, não um bug que você pode contornar. Conheço a escala disso em primeira mão: como Embaixador da Marca da Ahrefs, ajudei a divulgar um estudo em que coletamos todos os dados disponíveis na API em uma amostra muito grande de sites e descobrimos que o Google oculta o termo da palavra-chave em uma grande parcela dos cliques. Depois, incorporamos isso ao Ahrefs Rank Tracker — histórico completo dos seus dados do GSC, a porcentagem de cliques que vão para consultas anonimizadas e uma curva de CTR personalizada construída com seus próprios números. Quando alguém diz que a API retorna “todos os seus dados”, essa fatia anonimizada é o asterisco honesto.

Casos de uso comuns

• Relatórios automatizados — coletas agendadas para o Sheets ou um data warehouse.
• Dashboards de BI — Looker Studio ou BigQuery sobre os dados de Performance.
• Monitoramento de índice/cobertura em larga escala — URL Inspection, em lotes dentro da cota de 2 000/dia.
• Construção de curva de CTR — modelar a CTR esperada por posição a partir dos seus próprios dados.
• Alertas de anomalias — sinalizar quedas de cliques/impressões automaticamente.

É assim que as ferramentas de terceiros funcionam: quando a Ahrefs ou um conector do Looker Studio “integra o Search Console”, eles estão chamando essas mesmas APIs (e, cada vez mais, a exportação do BigQuery) em seu nome.

Resumo de IA

Uma visão condensada da versão Avançada:

• A API do Search Console = quatro APIs REST em webmaster-tools/v1: Search Analytics (dados de Performance), URL Inspection (status de indexação), Sitemaps e Sites. Não há paridade total com a interface — algumas coisas, como o teste ao vivo do URL Inspection, só existem na interface, e o acesso à API por si só não garante indexação, ranqueamento ou diagnóstico de tráfego.
• A autenticação é OAuth 2,0, sem chave de API. Dois escopos (webmasters, webmasters.readonly); contas de serviço para servidor a servidor, mas elas ainda precisam de acesso explícito à propriedade exata. siteUrl aceita uma propriedade de prefixo de URL ou uma propriedade de domínio sc-domain:example.com — corresponda à forma como ela é verificada. A API só retorna dados para propriedades que você verificou — o erro nº 1 para iniciantes.
• O Search Analytics retorna as primeiras linhas primeiro, não um despejo completo — “não garante retornar todas as linhas de dados, mas sim as principais”, independentemente da paginação. Dentro desse limite: 1–25 000 linhas por solicitação (padrão 1 000), contra ~1 000 na exportação da interface, e as cotas são divididas em limites de carga e limites de taxa de solicitação QPS/QPM/QPD.
• URL Inspection: 2 000 consultas/dia, 600/minuto por site, e ele relata apenas a versão indexada — não pode executar um teste ao vivo. Essa cota é a restrição real para monitoramento de índice em larga escala — faça lotes e agende em torno dela.
• A API de Sitemaps lista/obtém/envia/exclui sitemaps; a API de Sites lista/adiciona/remove propriedades.
• Para sites grandes, use a exportação de dados em massa do BigQuery — um pipeline agendado separado (não um quinto recurso de API) que fornece todos os dados de performance disponíveis diariamente, sem limite de linhas, exceto consultas anonimizadas.
• Consultas anonimizadas são uma lacuna genuína que nenhuma API ou exportação preenche — o trabalho do Patrick na Ahrefs quantificou o tamanho dessa fatia oculta.

Documentação oficial

Documentação de fonte primária do Google.

Referência da API Search Console

• Visão geral da API Search Console — o que a API faz e o requisito de propriedade verificada.
• Search Analytics: referência de consulta — os parâmetros rowLimit (1–25 000) e de dimensão.
• Referência da API URL Inspection — quais dados de status de indexação o método inspect retorna.
• Referência da API Sitemaps — listar, obter, enviar, excluir.
• Referência da API Sites — listar, adicionar, remover propriedades verificadas.
• Limites de uso — a tabela completa de cotas por site, por usuário e por projeto.
• Autorizando solicitações (OAuth 2.0) — escopos e o fluxo de autenticação.

Exportação de dados em massa

• Sobre a exportação de dados em massa (Central de Ajuda do Search Console) — agende uma exportação diária para o BigQuery de todos os dados de desempenho, exceto consultas anônimas.
• Anúncio da exportação de dados em massa (blog da Central de Pesquisa) — o post de lançamento que posiciona a exportação em massa para sites grandes.

Citações da fonte

Declarações oficiais da documentação do Google. Cada link é um link profundo que salta para a passagem citada na página de origem.

Google — o que a API faz e quem pode usá-la

• “view, add, or remove properties and sitemaps, run advanced queries for Google Search results data for the properties that you manage in Search Console, and test individual pages.” (tradução) «visualizar, adicionar ou remover propriedades e sitemaps, executar consultas avançadas para dados de resultados da Pesquisa Google para as propriedades que você gerencia no Search Console e testar páginas individuais.» — Documentação da API Search Console (Visão geral). Ir para a citação
• “You must have appropriate access (owner, full, read) to any Google Search Console account that you wish to access using the API.” (tradução) «Você deve ter acesso apropriado (proprietário, total, leitura) a qualquer conta do Google Search Console que deseje acessar usando a API.» — Documentação da API Search Console (Visão geral). Ir para a citação
• “All requests to the Google Search Console API must be authorized by an authenticated user.” (tradução) «Todas as solicitações à API do Google Search Console devem ser autorizadas por um usuário autenticado.» — Guia de autorização de solicitações. Ir para a citação

Google — API Search Analytics

• “[Optional; Valid range is 1–25,000; Default is 1,000]” (tradução) «[Opcional; o intervalo válido é de 1 a 25 000; o padrão é 1 000]» — o parâmetro rowLimit. — Search Analytics: referência de consulta. Ir para a citação
• “The URL of the property as defined in Search Console.” (tradução) «A URL da propriedade conforme definida no Search Console.» — o parâmetro siteUrl, cujos exemplos fornecem tanto a forma de prefixo de URL (http://www.example.com/) quanto a forma de propriedade de domínio (sc-domain:example.com). — Search Analytics: referência de consulta. Ir para a citação
• “The API is bounded by internal limitations of Search Console and does not guarantee to return all data rows but rather top ones.” (tradução) «A API é limitada por limitações internas do Search Console e não garante retornar todas as linhas de dados, mas sim as principais.» — Search Analytics: referência de consulta. Ir para a citação

Google — API URL Inspection

• “View the indexed, or indexable, status of the provided URL. Presently only the status of the version in the Google index is available; you cannot test the indexability of a live URL.” (tradução) «Veja o status indexado, ou indexável, da URL fornecida. Atualmente, apenas o status da versão no índice do Google está disponível; você não pode testar a indexabilidade de uma URL ativa.» — Referência da API URL Inspection. Ir para a citação

Google — API Sitemaps

• “Submits a sitemap for a site.” (tradução) «Envia um sitemap para um site.» / “Deletes a sitemap from this site.” (tradução) «Exclui um sitemap deste site.» / “Lists the sitemaps-entries submitted for this site, or included in the sitemap index file.” (tradução) «Lista as entradas de sitemap enviadas para este site ou incluídas no arquivo de índice de sitemaps.» — Referência da API Sitemaps. Ir para a citação

Google — exportação de dados em massa

• “Schedule a daily export of your Search Console performance data to BigQuery… you’ll see all the performance data available to Search Console for your property, with the exception of anonymized queries.” (tradução) «Agende uma exportação diária dos dados de desempenho do Search Console para o BigQuery… você verá todos os dados de desempenho disponíveis no Search Console para sua propriedade, com exceção das consultas anonimizadas.» — Central de Ajuda do Search Console: Sobre a exportação de dados em massa. Ir para a citação

Configuração do OAuth e lista de verificação da primeira chamada

Do zero até uma chamada funcional à API do Search Console:

• Confirme que você tem acesso verificado (proprietário, total ou leitura) à propriedade no Search Console — a API não retorna nada para propriedades não verificadas.
• Crie um projeto no Google Cloud Console.
• Ative a API Search Console para esse projeto.
• Crie credenciais: um cliente OAuth 2,0 (para aplicativos interativos/de usuário) ou uma conta de serviço (para automação servidor a servidor).
• Se usar uma conta de serviço, conceda a ela acesso à propriedade nas configurações do Search Console.
• Solicite o escopo correto: webmasters.readonly para relatórios, webmasters se você for enviar sitemaps ou gerenciar propriedades.
• Obtenha um token de acesso pelo fluxo OAuth (ou pela chave da conta de serviço).
• Confirme se o formato do siteUrl corresponde a como a propriedade é verificada: uma URL completa para uma propriedade de prefixo de URL, ou sc-domain:example.com para uma propriedade de domínio.
• Faça uma chamada de teste para searchAnalytics.query com um intervalo de datas pequeno e rowLimit: 10 para confirmar que os dados voltam.
• Planeje-se em torno das cotas: as taxas de solicitação do Search Analytics são generosas, mas também consomem uma cota de carga separada; a URL Inspection tem limite de 2 000/dia, 600/min por site — faça lotes de acordo. Não espere que a URL Inspection execute um teste ao vivo — isso é exclusivo da interface.
• Para dezenas de milhares de linhas, configure a exportação em massa do BigQuery em vez de paginar.

Os modelos mentais

1. Quatro APIs, uma autenticação. Search Analytics (leia seus dados de desempenho), URL Inspection (leia o status de indexação de uma URL), Sitemaps (gerencie sitemaps), Sites (gerencie propriedades). Todas as quatro passam pela mesma porta OAuth 2,0 e respeitam a mesma regra de propriedade verificada.

2. A escada de escala de dados. Escolha a ferramenta pelo volume:

• Olhada rápida → exportação da interface (~1 000 linhas).
• Scriptável, moderado → API Search Analytics (até 25 000/solicitação, pagine).
• Site grande, completo → exportação em massa do BigQuery (todos os dados, diariamente, sem limite de linhas). Suba na escada quando o degrau abaixo parar de caber nos seus dados.

3. Principais linhas, não todas as linhas. Assimile que a API retorna “as principais”, não tudo, e que consultas anônimas são excluídas tanto da API quanto da exportação. Se a completude for importante, o BigQuery é mais próximo — mas a fatia anônima desaparece independentemente.

4. Aritmética de cotas antes de construir. Antes de projetar um monitor de indexação, faça as contas: a URL Inspection é 2 000/dia por site. Um site com 50 mil URLs não pode ser inspecionado diariamente — então faça lotes, priorize ou agende em vários dias. Projete em torno do limite, não o descubra em produção.

Search Console API — folha de referência

As quatro APIs e seus principais limites

Autenticação

• Somente OAuth 2,0 — sem chave de API.
• Escopos: webmasters (leitura/gravação), webmasters.readonly (somente leitura).
• Contas de serviço para servidor a servidor (conceda a elas acesso à propriedade).
• Somente propriedades verificadas retornam dados.

Fatos rápidos

• A API retorna apenas linhas principais — não é garantido que esteja completa — independentemente da paginação.
• A exportação da interface limita-se a cerca de 1 000 linhas; a API fornece até 25 000/solicitação, pagine com startRow.
• As cotas do Search Analytics são divididas em limites de carga (baseados em recursos, em blocos de 10 min / 1 dia) e os limites de taxa de solicitação QPS/QPM/QPD acima.
• siteUrl aceita uma propriedade de prefixo de URL (http://www.example.com/) ou uma propriedade de domínio (sc-domain:example.com) — corresponda à forma como ela é verificada.
• O URL Inspection relata apenas a versão indexada — ele não pode executar um teste ao vivo; isso é apenas na interface.
• Consultas anônimas são excluídas da API e da exportação do BigQuery.
• Para dezenas de milhares de linhas → exportação em massa de dados do BigQuery — um pipeline agendado separado, não um quinto recurso da API.
• Expõe grande parte do relatório de desempenho (Search Analytics) e da ferramenta URL Inspection, mas não é paridade total com a interface.

Uma solicitação mínima do Search Analytics

Isso é ilustrativo, não pronto para copiar e colar — você precisará configurar suas próprias credenciais OAuth e ajustar as datas e a propriedade. Mostra a forma de uma chamada searchAnalytics.query: o corpo da solicitação com um intervalo de datas, as dimensões que você deseja e o rowLimit.

O corpo da solicitação (a parte que importa)

{
  "startDate": "2026-05-01",
  "endDate": "2026-05-31",
  "dimensions": ["query", "page"],
  "rowLimit": 25000,
  "startRow": 0
}

Exemplo em Python com a biblioteca google-api-python-client

# Illustrative only — assumes you've already built an authorized `service`
# via OAuth 2.0 (scope: webmasters.readonly) or a service account.
from googleapiclient.discovery import build

service = build("searchconsole", "v1", credentials=creds)

request = {
    "startDate": "2026-05-01",
    "endDate": "2026-05-31",
    "dimensions": ["query", "page"],
    "rowLimit": 25000,   # max per request; default is 1000
    "startRow": 0,       # bump by 25000 to paginate
}

response = service.searchanalytics().query(
    siteUrl="https://example.com/",  # URL-prefix property; use "sc-domain:example.com"
                                      # instead for a Domain property — must be verified
    body=request,
).execute()

for row in response.get("rows", []):
    print(row["keys"], row["clicks"], row["impressions"])

Para ir além de 25 000 linhas, faça um loop e incremente startRow em 25 000 até que uma solicitação não retorne linhas. Lembre-se de que o resultado ainda é “linhas principais”, não um despejo completo — para isso, use a exportação em massa do BigQuery.

Ferramentas que usam (ou encapsulam) a API do Search Console

• Google Cloud Console — onde você cria o projeto, ativa a API e gera as credenciais OAuth/de conta de serviço.
• Bibliotecas de cliente oficiais — as bibliotecas de cliente da API Google para Python, Java, JavaScript/Node, PHP e .NET encapsulam as chamadas REST.
• BigQuery — o destino para a exportação de dados em massa; consulte todos os seus dados de desempenho com SQL.
• Looker Studio — conecta-se ao Search Console (e ao BigQuery) para painéis criados com os mesmos dados.
• Ahrefs — integra a API do Search Console; seu Rank Tracker mostra o histórico completo do GSC, a parcela de cliques destinada a consultas anônimas e uma curva de CTR personalizada a partir dos seus próprios dados.
• Interface do Search Console — o relatório de desempenho e a ferramenta Inspeção de URL são os equivalentes manuais das APIs de análise de pesquisa e inspeção de URL, com uma lacuna que a API não consegue fechar: apenas a ferramenta de interface pode executar um teste ao vivo em uma URL.

Prompts para planejar o trabalho com a API do Search Console

Use estes prompts para moldar o código ou um plano de análise. Mantenha credenciais, tokens de atualização e chaves de conta de serviço fora de qualquer entrada de chat.

Projetar uma solicitação de Search Analytics

Cole a URL da sua propriedade, intervalo de datas, dimensões, filtros e meta de relatório.

Design a Google Search Console Search Analytics API request for the following reporting task.

Property: [sc-domain:example.com or exact URL-prefix property]
Date range: [start and end]
Goal: [the question the report must answer]
Dimensions: [date, query, page, country, device, searchAppearance, or hour]
Filters: [include/exclude rules]

Return:
1. The request body, including a rowLimit no higher than 25,000.
2. Pagination logic using startRow.
3. The aggregation and grouping needed after retrieval.
4. Warnings about top-rows-only data and anonymized queries.
5. A small validation query I can run before scheduling the full pull.

Do not invent credentials or assume the result is a complete census.

Planejar um cronograma de Inspeção de URL seguro para cotas

Cole um resumo em CSV ou contagens por prioridade de URL em vez de tokens confidenciais.

Create a quota-safe sampling and scheduling plan for the Search Console URL Inspection API.

Property: [property]
Total URLs: [count]
Priority groups: [critical templates, new URLs, changed URLs, long-tail sample]
Required revisit cadence: [daily, weekly, monthly]

Constraints from this article:
- 2,000 inspection queries per day per site.
- 600 inspection queries per minute per site.
- The API reports the indexed version, not a live test.

Return a daily allocation by priority group, a rotation method, retry/backoff rules,
and alerts for unexpected index or canonical states. Explain what cannot fit inside
the quota instead of silently dropping it.

Escolher entre API e exportação para BigQuery

Help me choose between the Search Console interface, Search Analytics API, and BigQuery bulk export.

Reporting need: [one-off analysis, dashboard, warehouse, anomaly alerts]
Expected rows per day: [estimate]
History required: [range]
Refresh cadence: [cadence]
Dimensions needed: [list]
Infrastructure available: [spreadsheet, script runner, BigQuery, BI tool]

Compare setup cost, row/completeness limits, automation, and maintenance. Account for
the API returning top rows and for anonymized queries being absent from every path.
End with one recommendation and the smallest proof-of-concept to validate it.

Recursos que valem seu tempo

Meu trabalho relacionado

• Blog da Ahrefs — meus posts — incluindo o trabalho com dados do GSC em escala e consultas anônimas.
• Agora no Ahrefs Rank Tracker: histórico completo do GSC + parcela de consultas anônimas — o recurso de curva de CTR e histórico do GSC que anunciei.

Documentação do Google

• Visão geral da API do Search Console e a página de limites de uso — as duas páginas para marcar como favoritas primeiro.
• Sobre a exportação de dados em massa — quando e como migrar para o BigQuery.

De outros

• Palavras-chave ocultas no GSC — o estudo da Ahrefs (cobertura do Search Engine Journal) — texto de terceiros sobre as descobertas de consultas anônimas.
• Análises aprimoradas do Search Console com BigQuery (SEJ) — uma visão prática do caminho de exportação em massa.
• Exportação de dados em massa: uma nova e poderosa forma de acessar seus dados do Search Console (blog Google Search Central) — o post de lançamento de fevereiro de 2023 da equipe do Search Console posicionando a exportação em massa para sites grandes.
• google-api-python-client (PyPI) — a biblioteca oficial de cliente Python usada para chamar a API do Search Console; também disponível para Node, Java, PHP e .NET por meio da família de bibliotecas de cliente das APIs do Google.
• r/TechSEO — a comunidade para solução de problemas de API e extração de dados.

Estatísticas que valem citar

• Limite de linhas do Search Analytics: 25 000 por solicitação (padrão 1 000) — em comparação com o limite de ~1 000 linhas da exportação da interface. Este é o principal motivo para usar a API. Fonte
• Cota do URL Inspection: 2 000 consultas/dia e 600/minuto por site — o teto rígido para monitoramento de índice em larga escala (10M/dia, 15 000/min por projeto). Fonte
• Consultas anonimizadas são excluídas até mesmo do caminho mais completo (exportação em massa do BigQuery) — uma lacuna real e inevitável nos seus dados de consulta. Fonte
• O Google oculta o termo da palavra-chave em uma grande parcela dos cliques — do estudo da Ahrefs que ajudei a divulgar, que extraiu todos os dados disponíveis da API em uma amostra muito grande de sites. Cobertura

Teste seus conhecimentos: API do Search Console

Cinco perguntas rápidas sobre as APIs, autenticação, limites de dados e escala. Escolha uma resposta para cada uma e depois confira o resultado.

Registro de alterações