Uma SERP API executa uma busca em um mecanismo de pesquisa para você e retorna a página de resultados como JSON estruturado: resultados orgânicos com suas posições, anúncios, featured snippets, resultados locais e mais. Em vez de construir scrapers para o Google e mantê-los funcionando, você envia uma requisição e lê os campos de que precisa.
Este guia percorre a configuração do zero: obter e armazenar uma chave de API, fazer sua primeira busca, obter resultados para o local e dispositivo corretos, lidar com erros e transformar resultados em uma verificação de ranking. Ele usa a SERP API da Shifter como exemplo; a maioria das SERP APIs funciona de forma semelhante.
Passo 1: obtenha sua chave de API
Toda requisição carrega uma chave de API. No painel da Shifter, abra SERP API, depois API Keys, e copie uma chave ativa.
Trate a chave como uma senha:
- Mantenha-a fora do código e dos repositórios. Armazene-a em uma variável de ambiente ou em um gerenciador de segredos.
- Use chaves separadas para desenvolvimento e produção sempre que possível, para que uma chave de teste vazada não afete a produção.
- Gire uma chave se ela puder ter sido exposta, e atualize-a em todos os lugares onde é usada.
export SHIFTER_SERP_KEY="your-key-here"Passo 2: execute sua primeira busca
A API é um único endpoint, https://serp.shifter.io/v1. Escolha o mecanismo de busca com engine e passe a consulta como q:
curl "https://serp.shifter.io/v1?engine=google&api_key=$SHIFTER_SERP_KEY&q=residential+proxies"A resposta é JSON. Para uma busca no Google, organic_results contém os resultados comuns, cada um com um position, title, link, displayed_link e snippet. Outras seções, como anúncios e resultados locais, aparecem quando a página de resultados as tem.
O mesmo endpoint cobre outros mecanismos de busca e superfícies do Google: altere engine para bing ou yandex para esses mecanismos de busca, ou para google_maps, google_news ou google_shopping para outros resultados do Google. O restante deste guia se aplica a todos eles; apenas os campos na resposta mudam.
Passo 3: obtenha resultados para o local e dispositivo corretos
Os resultados de busca diferem por local, idioma e dispositivo, muitas vezes bastante. Uma verificação de ranking que não fixa todos eles mede uma página de resultados diferente a cada vez.
| Parâmetro | O que define | Exemplo |
|---|---|---|
location | De onde a busca é feita | Austin,Texas,United States |
gl | O país dos resultados | us |
hl | O idioma da interface | en |
device | Resultados de desktop, mobile ou tablet | mobile |
Escreva o local por extenso (cidade, região, país), porque nomes curtos como “Springfield” são ambíguos. Nosso guia sobre SERP APIs com geo-targeting para SEO local explica por que a precisão de localização importa tanto.
Passo 4: lide com erros
As requisições podem falhar por motivos que passam e motivos que não passam:
- Tente novamente limites de taxa e erros temporários de servidor, com uma pausa que cresce a cada tentativa.
- Pare e corrija erros de autenticação e de requisição malformada; tentar novamente apenas repete a falha.
- Defina um timeout em cada requisição, para que uma busca lenta não trave uma execução inteira.
Juntando tudo
O helper abaixo lê a chave do ambiente, sempre envia local, idioma e dispositivo, tenta novamente os erros que valem a pena repetir, e inclui uma função que encontra em que posição um domínio aparece nos resultados orgânicos:
import os
import time
from urllib.parse import urlparse
import requests
API = "https://serp.shifter.io/v1"
RETRY = {408, 429, 500, 502, 503}
def google_search(query, location, gl="us", hl="en", device="desktop", session=None, attempts=3):
"""One Google search as seen from `location`, returned as parsed JSON."""
session = session or requests.Session()
params = {"engine": "google", "api_key": os.environ["SHIFTER_SERP_KEY"], "q": query,
"location": location, "gl": gl, "hl": hl, "device": device}
for attempt in range(1, attempts + 1):
response = session.get(API, params=params, timeout=60)
if response.status_code == 200:
return response.json()
if response.status_code not in RETRY or attempt == attempts:
raise RuntimeError(f"{query!r}: HTTP {response.status_code} {response.text[:200]}")
time.sleep(2 * attempt)
def rank_of(serp, domain):
"""Position of the first organic result on `domain`, or None if it is not there."""
for result in serp.get("organic_results", []):
host = urlparse(result["link"]).netloc.lower()
if host == domain or host.endswith("." + domain):
return result["position"]
return NoneVerificando em que posição um site aparece para duas palavras-chave, visto no mobile em Austin:
from serp import google_search, rank_of
keywords = ["emergency plumber", "water heater repair"]
for keyword in keywords:
serp = google_search(keyword, location="Austin,Texas,United States", device="mobile")
print(keyword, rank_of(serp, "example-plumbing.com"))Testamos os parâmetros de requisição, as repetições, o tratamento de erros e a busca de ranking do helper contra respostas simuladas.
Passo 5: transforme isso em monitoramento de ranking
Uma única busca é um retrato momentâneo. Monitoramento significa executar as mesmas buscas em uma programação regular e armazenar os resultados:
- Fixe a lista de palavras-chave e o local, idioma e dispositivo para cada uma.
- Execute em uma programação regular, diária ou semanal dependendo de quanto os rankings se movem no seu mercado.
- Armazene cada resposta completa com seu horário e configurações, não apenas a posição, para que você possa olhar para trás e ver o que mudou.
- Alerte sobre mudanças que importam: uma queda para fora dos três primeiros lugares, um concorrente aparecendo acima de você, um featured snippet perdido.
Nosso guia sobre automatizar o monitoramento diário de posição de palavras-chave cobre agendamento e armazenamento com mais profundidade. Se o rastreamento de ranking é uma parte central do seu trabalho, nossa página de monitoramento de SEO cobre a configuração mais ampla.
Erros comuns de configuração
- Nenhum local definido. Os resultados vêm então de um local padrão que provavelmente não é seu mercado.
- Misturar desktop e mobile entre execuções, o que faz os rankings pularem sem motivo real.
- Comparar pela URL exata em vez do domínio, de forma que uma página classificada que mudou de caminho pareça um ranking perdido.
- Armazenar apenas posições. Sem a resposta completa, você não consegue saber por que uma posição mudou.
- Codificar a chave diretamente, o que acaba indo parar em um repositório mais cedo ou mais tarde.
Perguntas frequentes
O que é uma SERP API?
Um serviço que executa buscas em mecanismos de pesquisa para você e retorna a página de resultados como dados estruturados, como resultados orgânicos com posições, anúncios, featured snippets e resultados locais, para que você não precise fazer scraping e parsing de páginas de busca você mesmo.
Como obtenho uma chave de SERP API?
Cadastre-se com um provedor de SERP API e crie uma chave em seu painel. No painel da Shifter, as chaves ficam em SERP API, depois API Keys. Armazene a chave em uma variável de ambiente em vez de no seu código.
Por que meus resultados de SERP API diferem do que vejo no Google?
Geralmente porque o local, idioma, dispositivo ou personalização diferem. Suas próprias buscas são personalizadas e vêm do seu local; defina explicitamente o local, idioma e dispositivo da API para corresponder ao mercado que você quer medir.
Com que frequência devo verificar rankings?
Diariamente para palavras-chave competitivas e mercados que mudam rápido, semanalmente para a maioria dos outros. Mantenha as configurações idênticas entre execuções para que as mudanças reflitam os resultados, não a medição.
Resumo
Configurar uma SERP API leva alguns passos: armazenar a chave com segurança, enviar a consulta com o mecanismo de busca, local, idioma e dispositivo fixados, tentar novamente apenas os erros que podem passar, e ler as posições dos resultados estruturados. Execute as mesmas buscas em uma programação regular, mantenha as respostas completas, e você terá um rastreador de ranking que mede a mesma página de resultados todas as vezes.