Como Construir um Rastreador de Classificação com a API de Pesquisa do Google em Python

TL;DR:

• Um rastreador de classificações é um pipeline de séries temporais, não uma única solicitação SERP. Ele deve preservar consulta, localização, idioma, dispositivo, domínio de pesquisa, hora de observação, URL de classificação e posição.
• Use uma API de Pesquisa quando precisar de observações SERP brutas. Use uma plataforma de SEO completa quando também precisar de descoberta de palavras-chave, relatórios, alertas e fluxos de trabalho do cliente.
• Normalize os nomes de host antes de combinar com um domínio alvo. Trate www.example.com, diferenças de esquema, caminhos e subdomínios de acordo com uma política explícita.
• Registre “não classificado” como dados. Não converta a ausência em posição zero e não mantenha a posição de ontem.
• Armazene a URL de classificação, bem como a classificação. Um domínio pode manter sua posição enquanto a página de destino muda.
• A API de Pesquisa do Google sem scrapings retorna dados de pesquisa estruturados. A implementação em Python abaixo solicita SERPs, analisa resultados orgânicos e escreve instantâneas CSV somente de anexação.

O que um Rastreador de Classificações Realmente Mede

Um rastreador de classificações observa onde um domínio alvo aparece em um conjunto de resultados de pesquisa específico em um momento específico.

Essa definição é deliberadamente estreita. A posição é condicional à consulta, país ou localização, idioma, domínio do Google, dispositivo, tipo de resultado e profundidade de paginação. Mude uma dimensão e a observação pertence a uma série diferente.

Um registro confiável deve conter pelo menos:

• palavra-chave
• domínio alvo
• posição observada ou um estado explícito de não classificado
• URL de classificação
• título do resultado
• configuração de país ou localização
• idioma
• dispositivo
• domínio do Google
• timestamp de observação

O rastreador nunca deve implicar que uma SERP amostrada é uma classificação universal. A personalização, experimentos, mudanças no índice e diferenças regionais fazem parte da pesquisa.

API de Pesquisa vs Plataforma de Rastreamento de Rankings

Uma API de Pesquisa e uma plataforma de rastreamento de rankings resolvem trabalhos relacionados, mas diferentes.

Escolha uma API quando as observações de classificação forem uma entrada para um produto interno, experimento ou data warehouse. Escolha uma plataforma quando analistas precisarem de uma interface pronta e fluxo de trabalho de relatórios.

Modelo de Solicitação da API de Pesquisa do Google

A API de Pesquisa do Google sem scrapings aceita parâmetros de pesquisa e retorna dados estruturados. A atual documentação da API de Pesquisa do Google documenta parâmetros comuns, incluindo consulta, país, idioma, domínio do Google, tipo de resultado, deslocamento e contagem de resultados.

Use o nome atual voltado para o cliente, API de Pesquisa do Google, na cópia do produto. Nomes de atores e rotas de API estáveis podem reter nomenclaturas internas mais antigas.

A solicitação usada por este guia é um POST para /api/v1/scraper/request com ator scraper.google.search. A autenticação deve estar no cabeçalho x-api-token. A entrada mantém a consulta e as configurações de pesquisa juntas, para que cada resposta possa ser rastreada até sua configuração de amostragem.

Construa o Rastreador em Python

O script abaixo realiza quatro trabalhos:

1. envia uma solicitação da API de Pesquisa do Google por palavra-chave;
2. encontra o primeiro resultado orgânico cujo nome de host corresponde à política alvo;
3. escreve uma instantânea CSV somente de anexação;
4. preserva uma posição em branco e URL quando o alvo não é encontrado.

Pré-requisito: a solicitação ao vivo requer uma chave API Scrapeless em SCRAPELESS_API_KEY. A lógica de correspondência, normalização e CSV pode ser testada localmente com um fixture de resposta salva antes de fazer uma solicitação autenticada.

import csv
import os
from datetime import datetime, timezone
from pathlib import Path
from urllib.parse import urlparse, urlunsplit

import requests

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


def normalized_host(value: str) -> str:
    candidate = value if "://" in value else urlunsplit(("https", value, "", "", ""))
    host = (urlparse(candidate).hostname or "").lower().rstrip(".")
    return host.removeprefix("www.")


def host_matches(result_url: str, target_domain: str, include_subdomains=True) -> bool:
    result_host = normalized_host(result_url)
    target_host = normalized_host(target_domain)
    if not result_host or not target_host:
        return False
    return result_host == target_host or (
        include_subdomains and result_host.endswith(f".{target_host}")
    )


def organic_results(payload: dict) -> list[dict]:
    if isinstance(payload.get("organic_results"), list):
        return payload["organic_results"]
    data = payload.get("data", {})
    if isinstance(data, dict) and isinstance(data.get("organic_results"), list):
        return data["organic_results"]
    return []


def find_rank(payload: dict, target_domain: str) -> dict:
    for fallback_position, item in enumerate(organic_results(payload), start=1):
        url = item.get("link") or item.get("url") or ""
        if host_matches(url, target_domain):
            return {
                "position": item.get("position", fallback_position),
                "ranking_url": url,
                "title": item.get("title", ""),
            }
    return {"position": None, "ranking_url": "", "title": ""}


def fetch_serp(keyword: str, *, gl="us", hl="en", device="desktop") -> dict:
    api_key = os.environ["SCRAPELESS_API_KEY"]
    response = requests.post(
        API_URL,
        headers={"x-api-token": api_key, "Content-Type": "application/json"},
        json={
            "actor": "scraper.google.search",
            "input": {
                "q": keyword,
                "gl": gl,
                "hl": hl,
                "google_domain": "google.com",
                "device": device,
                "start": 0,
            },
        },
        timeout=60,
    )
    response.raise_for_status()
    return response.json()


def append_snapshot(path: Path, row: dict) -> None:
    fields = [
        "observed_at", "keyword", "target_domain", "position",
        "ranking_url", "title", "gl", "hl", "device", "google_domain",
    ]
    exists = path.exists()
    with path.open("a", newline="", encoding="utf-8") as handle:
        writer = csv.DictWriter(handle, fieldnames=fields)
        if not exists:
            writer.writeheader()
        writer.writerow(row)


def track(keyword: str, target_domain: str, output="rank_history.csv") -> dict:
    settings = {"gl": "us", "hl": "en", "device": "desktop"}
    payload = fetch_serp(keyword, **settings)
    match = find_rank(payload, target_domain)
    row = {
        "observed_at": datetime.now(timezone.utc).isoformat(),
        "keyword": keyword,
        "target_domain": normalized_host(target_domain),
        "position": match["position"] or "",
        "ranking_url": match["ranking_url"],
        "title": match["title"],
        **settings,
        "google_domain": "google.com",
    }
    append_snapshot(Path(output), row)
    return row


if __name__ == "__main__":
    print(track("web scraping api", "scrapeless.com"))

A documentação da urlparse da biblioteca padrão explica por que a análise de nome de host deve usar um analisador de URL em vez de fatiamento de strings. O script remove apenas um www. inicial e opcionalmente aceita subdomínios; ajuste essa política antes de rastrear uma propriedade de domínio de múltiplas marcas.

Valide o Analisador de Posição

Antes de usar créditos ao vivo, salve uma resposta real da API da conta e execute o analisador contra ela. Inclua pelo menos estes fixtures:

Não calcule uma posição a partir da ordem da lista quando a API fornecer um campo position explícito sem entender primeiro a paginação. Em uma página de resultados posterior, o índice da lista um não é a posição global um. Preserve a posição fornecida ou adicione o deslocamento da página deliberadamente.

Armazenar Histórico Sem Reescrevê-lo

Instantâneas somente de adição são mais fáceis de auditar do que uma tabela "posição atual" mutável. Uma transformação posterior pode selecionar a linha mais recente por palavra-chave e mercado.

CSV funciona para um rastreador pessoal. Um serviço de produção deve usar uma chave de banco de dados que distingue palavra-chave, domínio, país ou localização, idioma, dispositivo, domínio do Google e hora de observação. A documentação da tabela SQLite é suficiente para um serviço local compacto; um armazém torna-se útil quando a série alimenta painéis e alertas. Para regras de identidade de URL além da política de nome de host usada aqui, consulte o padrão de sintaxe genérica de URI.

Mantenha tanto position quanto ranking_url. Essas mudanças significam coisas diferentes:

• mudanças de posição, URL inalterado: a mesma página de destino foi movida;
• posição inalterada, mudanças de URL: o Google selecionou uma página diferente;
• posição em branco: o domínio não foi encontrado dentro da profundidade do resultado amostrado;
• vários URLs do domínio aparecem: armazene a melhor posição e opcionalmente mantenha cada correspondência em uma tabela de detalhes.

Tratar Geo, Idioma, Dispositivo e Tempo

Trate as configurações de pesquisa como dimensões, não como rótulos opcionais adicionados posteriormente.

• gl indica um contexto de país.
• hl controla o idioma da interface.
• google_domain seleciona a propriedade do Google.
• device separa observações de desktop e mobile quando suportado.
• uma configuração de localização precisa pode modelar um mercado de forma mais restrita do que um país.
• o timestamp deve usar UTC no armazenamento e converter apenas para exibição.

Não misture uma série em nível de cidade com uma série em nível de país sob a mesma linha de gráfico. Da mesma forma, um resultado mobile não deve silenciosamente substituir uma observação de desktop.

O tempo de amostragem também é importante. Execute grupos de palavras-chave comparáveis em uma janela delimitada. Se um lote se estender por muitas horas, armazene o timestamp de cada solicitação em vez de uma data para todo o trabalho.

Calcular Custo Sem Publicar um Preço Desatualizado

O cálculo estável é mais útil do que um valor de plano copiado:

monthly requests = keywords × markets × devices × pages sampled × runs per month

Então aplique a taxa atual da conta e a política de tratamento de falhas. Separe as solicitações planejadas de tentativas repetidas e falhadas para que uma equipe de operações possa explicar a fatura. Verifique precificação Scrapeless no momento da implementação, em vez de incorporar um número que pode se tornar obsoleto antes do código.

Comece a Raspagem com Scrapeless

Potencialize seu fluxo de trabalho de raspagem da web e automação com Scrapeless!
Inscreva-se hoje e receba $5 em crédito gratuito — sem necessidade de cartão de crédito.

Reivindique seu crédito gratuito agora no Painel Scrapeless.

Lista de Verificação de Produção

• Fixe um contrato de esquema para os campos que o parser consome.
• Mantenha a chave da API em um gerenciador de segredos ou variável de ambiente.
• Repita apenas os pedidos delimitados após falhas de serviço temporárias; não faça loops indefinidamente.
• Armazene as configurações de solicitação ao lado de cada observação.
• Distinguir não classificado de solicitação falhada.
• Rastrear a URL de classificação, não apenas a posição numérica.
• Preserve um fixture de resposta redigida para testes de regressão do parser.
• Respeitar termos aplicáveis, requisitos de privacidade e legislação local.
• Alerta sobre lotes ausentes e desvio de esquema antes de alertar sobre movimento de SEO.

Conclusão

Um rastreador de classificação útil é um sistema de observação disciplinado. A API de Pesquisa do Google Scrapeless fornece registros SERP estruturados; o valor vem da correspondência explícita, dimensões de pesquisa completas, histórico somente de adição e tratamento honesto de resultados ausentes.

Comece com uma palavra-chave, um mercado, um dispositivo e um fixture verificado. Uma vez que a série esteja estável, expanda o lote e conecte o CSV ou banco de dados a um painel. Para fluxos de trabalho adjacentes, consulte o guia da API de Pesquisa do Google.

Construa Sua Primeira Instantânea SERP

Junte-se à comunidade Scrapeless para obter ajuda na implementação e padrões de pipeline de dados: Discord · Telegram.
Crie uma conta gratuita em app.scrapeless.com, execute uma consulta limitada e valide a resposta salva antes de agendar o rastreador.

FAQ

Q: O que é uma API de rastreio de classificação?

Uma API de rastreio de classificação fornece observações de resultados de pesquisa ou classificação que o software pode armazenar e analisar. Uma API SERP retorna registros de resultados brutos; uma API dedicada de rastreamento de classificação também pode fornecer projetos, histórico, alertas e relatórios.

Q: Como posso encontrar a posição do meu domínio nos resultados orgânicos?

Analise cada URL de resultado orgânico com um analisador de URL, normalize o nome do host, aplique uma política explícita de apex/subdomínio e retorne a posição fornecida do primeiro resultado correspondente. Evite correspondência de substring.

Q: Que posição devo armazenar quando o domínio está faltando?

Armazene uma posição nula ou em branco mais um estado explícito de não classificado para a profundidade amostrada. Não use zero e não carregue a observação anterior para frente.

Q: Com que frequência um rastreador de classificação deve ser executado?

Escolha uma cadência com base na decisão que os dados suportam. A amostragem diária é comum para monitoramento ativo de SEO, enquanto relatórios estratégicos mais lentos podem precisar de menos. A consistência e configurações comparáveis são mais importantes do que a frequência máxima.

Q: Este script prova uma classificação universal do Google?

Não. Ele registra uma observação estruturada para consulta, mercado, idioma, dispositivo, domínio, profundidade e configurações de tempo definidos. Os resultados de busca podem variar fora dessa configuração de amostragem.