API do Search Console: como obter acesso e o que ela retorna
Por Toy Wen Da, Cofundador · Atualizado em · 6 min de leitura
Traduzido do original em inglês. Ler em inglês
A API do Search Console é a interface programática do Google para os mesmos dados que você vê no Google Search Console: cliques, impressões, posição e status de indexação, entregues por código em vez de pelo painel. Para usá-la, ative a API no Google Cloud Console, crie credenciais e depois autorize essas credenciais em uma propriedade que você já possui no Search Console.
Antes de construir qualquer coisa personalizada, verifique se você realmente precisa de acesso direto à API. O recurso de tráfego do site do SearchBlueprint já reúne os números do Search Console, do Google Analytics e das visitas de crawlers de IA em uma só visão, o que responde à pergunta "o que está acontecendo com meus cliques e impressões" para a maioria dos donos de site, sem uma linha de código.
O que a API do Search Console faz
É uma API REST publicada pelo Google que espelha a maior parte do painel do Search Console: desempenho na busca (consultas, páginas, países, dispositivos), status de sitemaps e resultados da inspeção de URL. Você a chama a partir de um script, de um serviço de back-end ou de uma ferramenta, e ela devolve JSON estruturado em vez de uma tela que você precisa ler manualmente.
Ela não entrega nada que o Search Console já não mostre. O que muda são o volume e a automação: você pode puxar anos de dados, combinar várias propriedades ou atualizar um relatório toda manhã sem que uma pessoa abra uma aba do navegador.
Como obter acesso: chave de API, OAuth e ativação da API
Uma simples chave de API não basta. Os endpoints de Search Analytics do Google exigem um usuário ou uma conta de serviço autorizados na propriedade específica, porque os dados estão ligados a quem verificou a propriedade. A sequência abaixo segue o console atual.
Etapa 1: ative a API no Google Cloud Console
Acesse o Google Cloud Console, selecione ou crie um projeto, abra o menu APIs & Services, depois Library. Pesquise por "Google Search Console API", clique nela e clique em Enable.
Etapa 2: crie as credenciais
Ainda em APIs & Services, abra Credentials e depois Create Credentials. Para scripts e tarefas entre servidores, escolha Service Account e baixe a chave JSON dela. Para um app que age em nome de um usuário logado, escolha um OAuth client ID.
Etapa 3: conceda acesso no Search Console
A API só enxerga as propriedades às quais a identidade autenticada tem acesso. Se você criou uma conta de serviço, copie o endereço de e-mail dela e adicione-a como usuária em Settings > Users and permissions. Acesso Full ou Restricted é o mínimo, e a escolha certa depende de a conta precisar enviar sitemaps ou apenas ler dados.
Etapa 4: faça sua primeira chamada
Com as credenciais em mãos, autentique-se e chame o método query do Search Analytics, informando uma data inicial, uma data final e as dimensões que você quer (consulta, página, país, dispositivo). É aqui que costuma aparecer uma divergência de verificação. Se a conta de serviço não enxerga a propriedade, provavelmente a própria verificação no Search Console precisa de uma nova olhada, e vale corrigi-la na origem antes de depurar a chamada da API.
O que você pode puxar: visão geral dos endpoints
| Endpoint | O que retorna | Uso típico |
|---|---|---|
| Search Analytics query | Cliques, impressões, CTR e posição por consulta/página/país/dispositivo | Dashboards de ranking e tráfego |
| Sitemaps | Lista, envia ou exclui entradas de sitemap | Reenvio automático do sitemap após uma reconstrução |
| URL Inspection | Status de indexação, canonical e usabilidade em dispositivos móveis de uma URL | Verificar se uma página foi indexada após a publicação |
| Sites | Lista ou adiciona propriedades às quais a conta tem acesso | Ferramentas de agências com vários sites |
API do Search Console x exportação manual x ferramentas no-code
| Opção | Ideal para | Esforço de configuração | Principal limitação |
|---|---|---|---|
| Exportação pela interface do Search Console | Uma verificação única e ocasional | Nenhum | Linhas limitadas, sem agendamento, sem automação |
| Chamadas diretas à API | Dashboards personalizados, desenvolvedores | Moderado a alto (OAuth, código) | Você mantém a autenticação e o código |
| Wrappers de API no-code | Quem não é desenvolvedor, mas ainda precisa de JSON | Baixo | Mensalidade, menos controle sobre os campos |
| Plataformas de integração (iPaaS) | Produtos SaaS que incorporam dados do GSC para os clientes | Moderado | Feitas para fornecedores, não para os relatórios de um único site |
Os wrappers no-code existem para pular o trabalho com OAuth e endpoints. O conector de Search Console do NoCodeAPI, por exemplo, transforma chamadas de Search Analytics e de sitemaps em um único endpoint JSON autenticado. Fornecedores como a Paragon anunciam integrações nativas com o Search Console construídas com cerca de 70% menos esforço de engenharia do que escrever a lógica de OAuth e de sincronização do zero, mas elas são voltadas a equipes de SaaS que entregam dados do Search Console dentro do próprio produto, e não a quem quer ver seus próprios números.
Quando as ferramentas gratuitas bastam e quando não bastam
A própria interface do Search Console basta para verificar uma URL, responder a uma dúvida pontual, como se uma página foi indexada, ou dar uma olhada nas principais consultas do mês passado. Ela não foi feita para nada recorrente nem espalhado por muitas propriedades.
A API, ou uma ferramenta construída sobre ela, compensa quando você precisa de:
- Um relatório agendado que se atualiza sem que ninguém abra o Search Console
- Dados de mais propriedades do que você consegue percorrer em abas manualmente
- Um histórico além do que a interface mostra com facilidade
- Dados de busca combinados com outras fontes
Se você seguir pelo caminho de combinar dados, ajuda conhecer a diferença real entre o Search Console e o Analytics, já que eles respondem a perguntas diferentes e nenhum substitui o outro.
Erros comuns
- Usar uma chave de API em vez de OAuth ou de uma conta de serviço. As chamadas ao Search Analytics falham sem a autorização adequada, por mais válida que a chave pareça.
- Esquecer de adicionar a conta de serviço como usuária no Search Console. A credencial da API e a permissão na propriedade são duas etapas separadas.
- Supor que a API retorna mais histórico do que a interface. Ambas puxam dos mesmos dados subjacentes, então a vantagem da API é a automação, e não meses extras de registros.
- Fixar no código os intervalos de datas e as dimensões. Consultas que não paginam corretamente truncam os resultados em silêncio em sites de alto tráfego.
Perguntas frequentes
Preciso pagar pela API do Search Console?
Não. A API é gratuita dentro dos limites de cota padrão do Google, e você só paga se criar ou comprar uma ferramenta em cima dela.
Qual é a diferença entre uma chave de API e o OAuth no Search Console?
Uma chave de API identifica um projeto. O OAuth ou uma conta de serviço identifica e autoriza um usuário ou uma conta específica em uma propriedade, e os dados do Search Analytics exigem este último.
Posso usar a API do Search Console sem programar?
Sim, por meio de conectores no-code que envolvem a API em um endpoint JSON mais simples. Você ainda precisará se autenticar no Google e gerenciar uma conta com esse provedor.
Quantos dados posso puxar por requisição?
A documentação do Google descreve os limites de linhas e de cota de cada método. Contas grandes normalmente precisam paginar as requisições em vez de puxar tudo em uma única chamada.
A API funciona para propriedades que não verifiquei?
Não. O acesso está ligado à propriedade verificada no Search Console, então a credencial que você usa precisa ser adicionada antes como usuária dessa propriedade.
Para a referência técnica completa, incluindo cotas e parâmetros dos métodos, consulte a documentação da API do Search Console do próprio Google.
Check-up dos seus números antes de construir qualquer coisa
Se o objetivo é ter visibilidade de cliques, impressões e de como os crawlers de IA tratam suas páginas, a API do Search Console não é necessária. Pule a configuração do OAuth e veja os mesmos dados reunidos na visão de tráfego do site do SearchBlueprint. Para uma visão mais ampla de como seu site está se saindo na busca neste momento, fale com a equipe, que vai lhe entregar um relatório de amostra criado a partir dos dados do seu próprio site.
Recursos / Referências
Fontes
Sobre o autor
O SearchBlueprint pesquisou, escreveu e avaliou este artigo com o mesmo pipeline de conteúdo que nossos clientes usam nos próprios sites. A nota que aparece na assinatura é a que nosso mecanismo de conteúdo deu a esta página antes de ela ser publicada. Nada aqui passa por revisão manual, e esse é justamente o ponto: é o resultado do produto, publicado onde qualquer pessoa pode conferir.