Construa um Rastreador de Rankings com Scrapeless Deep SerpApi

Resumo:

• Um rastreador de posição é um loop, não uma planilha. Consulte o Google para cada palavra-chave, leia as posições orgânicas, descubra onde seu domínio se posiciona e anote o número em um cronograma — essa é a máquina inteira.
• A parte difícil é conseguir uma SERP limpa e analisável. O Google personaliza e limita os resultados, então um rastreador de posição precisa de uma fonte de pesquisa que retorne organic_results estruturados com uma position e um link estáveis em cada chamada.
• O Deep SerpApi da Scrapeless retorna resultados do Google como JSON. Um POST com {"q": "<keyword>"} contra o ator scraper.google.search retorna um array de organic_results — cada entrada contém uma position e um link, que é tudo que um rastreador de posição precisa para corresponder ao seu domínio.
• A correspondência de domínio é uma comparação de host, não uma busca por string. Analise o link de cada resultado para seu host, remova www. e compare com seu domínio alvo — assim, blog.seudominio.com e seudominio.com/caminho contam como um acerto.
• Instantâneas ao longo do tempo transformam posições em deltas. Armazene cada execução com base na data, então compare hoje com a última execução armazenada para ver quais palavras-chave subiram, caíram ou saíram completamente dos resultados.
• Grátis para começar. Novas contas da Scrapeless incluem créditos gratuitos do Deep SerpApi — inscreva-se em app.scrapeless.com e execute o rastreador neste guia contra seu próprio conjunto de palavras-chave.

Introdução: construa o rastreador de posições, não o alugue

A posição de busca é uma posição em uma lista. Para uma determinada palavra-chave, seu domínio está na posição orgânica 3, ou 11, ou em nenhum lugar na primeira página — e esse número muda à medida que o Google reorganiza e os concorrentes publicam. Rastrear isso é a diferença entre saber que uma página caiu de 4 para 9 na semana passada e descobrir quando o tráfego já foi embora.

A maioria dos tutoriais sobre "construir um rastreador de posição" termina em uma planilha do Google que você atualiza manualmente ou em uma fórmula que coleta uma célula de cada vez e quebra no momento em que o Google muda sua marcação. Isso funciona para cinco palavras-chave verificadas uma vez por mês. Não escala para um conjunto de palavras-chave que você realmente se importa e não fornece histórico para comparações.

Este guia constrói um rastreador de posição programático real em Python, com base no Scrapeless Deep SerpApi. A API retorna os resultados orgânicos do Google como JSON estruturado, então o rastreador permanece pequeno: consulte uma palavra-chave, analise as posições, faça a correspondência com seu domínio, armazene a instantânea e compare execuções para calcular movimento. No final, você terá um script que pode usar em qualquer conjunto de palavras-chave e executar em um cronograma.

O Que Você Pode Fazer Com Um Rastreador de Posições Programático

• Rastrear um conjunto de palavras-chave em um cronograma. Execute o mesmo script diariamente ou semanalmente contra dezenas de palavras-chave e construa um histórico de posições sem tocar em um navegador.
• Acompanhar a distribuição de palavras-chave de uma única página. Direcione o rastreador para as palavras-chave alvo de uma URL e veja quais termos ela classifica e onde.
• Detectar quedas antes que o tráfego faça isso. Uma posição que muda de 5 para 14 é um sinal sobre o qual você pode agir no dia em que acontece, e não no final do mês.
• Comparar classificações regionais. A mesma palavra-chave classifica de forma diferente por país, então um rastreador que varia o parâmetro gl mostra sua posição em cada mercado.
• Integrar classificações em seus próprios painéis. Como cada resultado é JSON, os dados de posição vão direto para um banco de dados, um caderno ou um trabalho de relatórios sem necessidade de colagem.
• Auditar uma migração ou redesign. Capture classificações antes de uma mudança de site e compare depois, para que uma regressão apareça como uma lista de palavras-chave eliminadas.

Por Que Scrapeless Deep SerpApi

O Scrapeless Deep SerpApi é um endpoint gerenciado de busca do Google que retorna a SERP como JSON estruturado em vez de HTML bruto. Para um rastreador de posição especificamente, ele oferece:

• organic_results estruturados — cada resultado é um objeto com position, title e link, então não há análise de HTML e nenhum seletor CSS que quebre com a próxima mudança de layout do Google.
• Um campo position estável — a API relata a classificação de cada resultado orgânico, que é o valor exato que um rastreador de posição registra.
• Controle de país e idioma — os parâmetros gl e hl permitem medir classificações por mercado a partir de um único endpoint.
• Egressos residenciais nos bastidores — as pesquisas são feitas através de proxies residenciais em mais de 195 países, então os resultados refletem a SERP de um usuário real em vez de um marcado por data center.
• Uma resposta inline — o ator scraper.google.search retorna resultados na mesma solicitação, então o rastreador lê o JSON diretamente, sem etapa de polling.

Obtenha sua chave de API no plano gratuito em app.scrapeless.com.

Pré-requisitos

• Python 3.10 ou mais recente
• A biblioteca requests (pip install requests)
• Uma conta Scrapeless e chave de API — inscreva-se em app.scrapeless.com
• Um conjunto de palavras-chave e o domínio alvo que você deseja rastrear
• Familiaridade básica com o terminal

Leia sua chave de API do ambiente para que ela nunca apareça no script:

export SCRAPELESS_API_KEY="seu_token_api_aqui"

Passo 1 — Consultar o Google por uma palavra-chave

A menor unidade do rastreador é uma consulta de palavra-chave. Envie um POST para o endpoint Deep SerpApi com o ator scraper.google.search e um objeto input contendo a consulta. O campo q é a palavra-chave; gl e hl definem o país e o idioma da interface, de modo que cada execução meça o mesmo mercado.

import os
import requests

ENDPOINT = "https://api.scrapeless.com/api/v1/scraper/request"


def search(query, gl="us", hl="en"):
    payload = {
        "actor": "scraper.google.search",
        "input": {"q": query, "gl": gl, "hl": hl},
    }
    response = requests.post(
        ENDPOINT,
        json=payload,
        headers={"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
    )
    response.raise_for_status()
    return response.json()


data = search("navegador de raspagem scrapeless")
results = data.get("organic_results", [])
print(f"{len(results)} resultados orgânicos")
for result in results[:5]:
    print(result["position"], result["link"])

A resposta é um objeto JSON retornado em uma única rodada de semântica HTTP; organic_results é o array que o rastreador lê. Cada elemento apresenta uma position (o ranking na página) e um link (a URL do resultado). title, snippet e source também estão presentes, mas um rastreador de posição precisa apenas de position e link.

Passo 2 — Analisar as posições orgânicas

A consulta no Passo 1 retorna o objeto SERP completo — resultados orgânicos, além de anúncios, pesquisas relacionadas e vídeos inline quando o Google os exibe. O rastreador trabalha apenas com organic_results, e somente com dois campos por entrada. Reduza cada resultado a um par (position, link) para que a etapa de correspondência tenha uma lista limpa para escanear.

def organic_positions(data):
    pairs = []
    for result in data.get("organic_results", []):
        pairs.append((result["position"], result["link"]))
    return pairs


positions = organic_positions(search("navegador de raspagem scrapeless"))
for position, link in positions:
    print(position, link)

position é o ranking que o Google atribuiu ao resultado na página retornada. Leia-o diretamente do campo em vez de contar o índice da lista, para que o valor permaneça correto mesmo quando a API omite um tipo de resultado ou a composição da página muda entre execuções.

Passo 3 — Correspondência do seu domínio a um ranking

Um ranking é a position do seu domínio nessa lista. A correspondência deve ser feita com o host, e não com um subconjunto da URL, de modo que uma busca por "seudominio" no link bruto não corresponda erroneamente ao caminho de um concorrente ou a uma string de consulta. Extraia cada link para seu host, remova um www. inicial e trate um subdomínio como uma correspondência também.

from urllib.parse import urlparse


def host_of(url):
    host = urlparse(url).netloc.lower()
    return host[4:] if host.startswith("www.") else host


def rank_of(domain, data):
    domain = domain.lower()
    for result in data.get("organic_results", []):
        host = host_of(result["link"])
        if host == domain or host.endswith("." + domain):
            return result["position"]
    return None


data = search("navegador de raspagem scrapeless")
rank = rank_of("scrapeless.com", data)
print("scrapeless.com:", rank if rank is not None else "não nos resultados retornados")

rank_of retorna a primeira posição que seu domínio ocupa, ou None quando não aparece nos resultados retornados. Um None é um dado real — significa que o domínio não está na página que a API retornou para aquela palavra-chave, e o rastreador deve registrar isso, não ignorá-lo.

Obtenha sua chave de API no plano gratuito: app.scrapeless.com

Passo 4 — Rastrear um conjunto de palavras-chave e armazenar instantâneas

Uma única palavra-chave não é um rastreador. Execute a correspondência em um conjunto de palavras-chave, registre o resultado com uma data e anexe-o a um arquivo de histórico. Cada instantânea é uma execução: uma data mais um mapa de palavra-chave a posição. Armazená-las como uma lista mantém toda a linha do tempo em um só lugar para a etapa de comparação.

import json
from datetime import date, timezone, datetime
from pathlib import Path

HISTORY = Path("rank_history.json")


def snapshot(domain, keywords):
    ranks = {}
    for keyword in keywords:
        ranks[keyword] = rank_of(domain, search(keyword))
    return {"date": date.today().isoformat(), "domain": domain, "ranks": ranks}


def append_snapshot(snap):
    history = json.loads(HISTORY.read_text()) if HISTORY.exists() else []
    history.append(snap)
    HISTORY.write_text(json.dumps(history, indent=2))
    return history


keywords = [
    "navegador de raspagem scrapeless",
    "scrapeless deep serp api",
    "navegador em nuvem anti detecção",
]
snap = snapshot("scrapeless.com", keywords)
append_snapshot(snap)
for keyword, position in snap["ranks"].items():
    print(f"{position if position is not None else '—':>3}  {keyword}")

Cada execução anexa um instantâneo. O conjunto de palavras-chave é definido por você; troque os termos que uma página deve classificar. As posições que retornam None são registradas como null na história, então uma palavra-chave que saiu da página é um evento registrado, em vez de uma lacuna.

Passo 5 — Calcule as deltas de classificação entre as execuções

A história só é útil quando você faz a diferença. Compare o último instantâneo com o anterior para o mesmo domínio e classifique cada palavra-chave: melhorou, caiu, inalterada, nova na classificação ou saiu. A delta é a posição anterior menos a atual, então um número positivo significa que o domínio subiu na página.

def deltas(history, domain):
    runs = [s for s in history if s["domain"] == domain]
    if len(runs) < 2:
        return {}
    previous, current = runs[-2]["ranks"], runs[-1]["ranks"]
    report = {}
    for keyword, now in current.items():
        before = previous.get(keyword)
        if now is None and before is not None:
            report[keyword] = "saiu dos resultados"
        elif now is not None and before is None:
            report[keyword] = f"novo em {now}"
        elif now is not None and before is not None:
            move = before - now
            report[keyword] = "sem mudança" se move == 0 else f"{move:+d} (era {before}, agora {now})"
    return report


history = json.loads(HISTORY.read_text())
for keyword, change in deltas(history, "scrapeless.com").items():
    print(f"{keyword}: {change}")

Na primeira execução, não há nada para diferenciar, então deltas retorna vazio — o rastreador apenas armazena a linha de base. A partir da segunda execução, cada palavra-chave carrega um rótulo de movimento que você pode direcionar para um alerta, um painel ou um relatório semanal. Programe o par Passo 4 + Passo 5 com cron ou um trabalho de CI e o rastreador de classificação se executa automaticamente.

O Que Você Recebe de Volta

O arquivo de histórico é a saída do rastreador: um instantâneo por execução, cada um com uma data mais um mapa de palavras-chave para posição. A forma abaixo é exatamente o que append_snapshot escreve.

// amostra ilustrativa — o esquema é exatamente o que append_snapshot escreve; os valores dos campos são ilustrativos.
[
  {
    "date": "2026-06-16",
    "domain": "seudominio.com",
    "ranks": {
      "sua palavra-chave principal": 4,
      "sua palavra-chave secundária": 11,
      "uma palavra-chave para a qual você ainda não está classificado": null
    }
  },
  {
    "date": "2026-06-23",
    "domain": "seudominio.com",
    "ranks": {
      "sua palavra-chave principal": 2,
      "sua palavra-chave secundária": 9,
      "uma palavra-chave para a qual você ainda não está classificado": 18
    }
  }
]

Algumas observações honestas de execuções de palavras-chave ao vivo:

• As contagens de posição vêm do campo position da API. Leia-as diretamente; não infira a classificação a partir do índice do array, porque o resultado retornado varia entre as execuções.
• As contagens de resultados orgânicos variam por consulta. Uma palavra-chave pode retornar seis resultados orgânicos em uma execução e oito em outra, então um None para um domínio de classificação profunda pode simplesmente significar que estava abaixo do conjunto retornado naquele dia.
• snippet_highlighted_words é condicional. Alguns resultados carregam isso e outros não; um rastreador de classificação ignora, mas qualquer coisa que leia outros campos deve tratá-los como anuláveis.
• O país importa. A mesma palavra-chave classifica de maneira diferente por valor de gl, então fixe um país por palavra-chave rastreada e mantenha-o constante entre as execuções para comparar como com como.

Conclusão: escale seu pipeline de rastreamento de classificação

Um rastreador de classificação se reduz a cinco movimentos: consultar uma palavra-chave, analisar as posições orgânicas, combinar seu domínio no host, armazenar um instantâneo datado e diferenciar em relação à última execução. Construído sobre Deep SerpApi, cada um desses movimentos lê um array estruturado de organic_results em vez de lutar contra o HTML do Google, então o rastreador todo fica abaixo de cem linhas.

A partir daqui, escale-o ao longo dos eixos que importam: amplie o conjunto de palavras-chave, varie gl por mercado e envie instantâneos para um banco de dados para que a história sobreviva a um único arquivo. A mesma abordagem orientada a JSON se estende a outras superfícies cobertas no guia da API Scrapeless Scraper. Confira os planos de preços e a documentação do Deep SerpApi para o conjunto completo de parâmetros, fixe um país por palavra-chave, leia posições do campo position e trate um domínio ausente como um real null.

Pronto para Construir Seu Pipeline de Pesquisa Potencializado por IA?

Junte-se à nossa comunidade para reivindicar um plano gratuito e conectar-se com desenvolvedores que estão construindo pipelines de rastreamento de classificação e pesquisa: Discord · Telegram.
Inscreva-se em app.scrapeless.com para obter créditos gratuitos do Deep SerpApi e adapte o rastreador acima ao conjunto de palavras-chave e mercados que seu projeto precisa.

Perguntas Frequentes

P: É legal rastrear classificações do Google com uma API?
Consultar resultados de pesquisa publicamente visíveis é geralmente como o rastreamento de classificações funciona, e o Deep SerpApi retorna o mesmo SERP público que um navegador retornaria — as páginas classificadas que o Google rasteou e indexou, o mesmo conjunto de URLs que os proprietários de sites expõem através do protocolo Sitemaps. As regras variam conforme a jurisdição e o caso de uso, por isso revise os termos do Google juntamente com as diretrizes de rastreamento em o Protocolo de Exclusão de Robôs e consulte um advogado para sua aplicação específica.

P: Como isso difere de um rastreador de classificação do Google Sheets?
Um rastreador de planilhas verifica uma célula de cada vez e não armazena um histórico real para comparação. O script aqui consulta um conjunto completo de palavras-chave programaticamente, registra instantâneas datadas e computa movimentos entre execuções, portanto, ele escala para grandes conjuntos de palavras-chave e roda em um cronograma.

P: Preciso de um proxy para executar o rastreador?
Nenhuma configuração de proxy separada é necessária. O Deep SerpApi direciona buscas através de egressos residenciais em mais de 195 países internamente, então os resultados refletem o SERP de um usuário real sem que você precise gerenciar IPs.

P: Como rastrear classificações para um país específico?
Defina o parâmetro gl para o código do país e hl para o idioma ao chamar search. Mantenha o mesmo gl para uma determinada palavra-chave nas execuções para que o histórico de posições compare semelhantes.

P: O que significa uma posição null?
Significa que o domínio não estava presente nos resultados orgânicos que a API retornou para essa palavra-chave nessa execução — ou ele está classificado abaixo do conjunto retornado ou caiu da página. O rastreador registra isso como um evento real, então uma queda aparece nos deltas.

P: Com que frequência o rastreador deve ser executado?
Diariamente ou semanalmente cobre a maioria das necessidades. Programe a etapa de instantânea e dif para rodar com cron ou um trabalho de CI; as posições se movem na linha do tempo do Google, então polling sub-diário raramente adiciona sinal.

P: Posso combinar subdomínios e caminhos ao meu domínio?
Sim. O comparador rank_of compara pelo host e trata um subdomínio como um acerto, então blog.seudominio.com e seudominio.com/pagina contam ambos como seu domínio classificando.