Construa um Conjunto de Dados de Instantâneo do Google SERP para Pesquisa em SEO

TL;DR:

• O rastreamento do SERP do Google precisa de um registro da pesquisa, não apenas de uma coluna de classificação. Salve a solicitação exata, os timestamps do cliente, o estado de processamento e a resposta bruta juntos.
• Construa um histórico a partir de suas próprias observações. Uma solicitação de pesquisa atual não preenche os dias antes do início da coleta.
• Compare resultados orgânicos dentro de um contexto fixo. Mudanças na consulta, país, idioma ou profundidade de coleta criam um grupo de comparação diferente.

Um valor de classificação perde seu significado quando a planilha não registra mais qual pesquisa o produziu. A mesma página pode aparecer em diferentes consultas, em diferentes mercados e ao lado de diferentes módulos de resultado. Um conjunto de dados útil mantém essas condições anexadas a cada observação.

O rastreamento do SERP do Google começa com uma coleta repetível e uma definição clara do que conta como um resultado comparável. Scrapeless Google Search API fornece dados de pesquisa estruturados; a aplicação fornece a política de armazenamento e o histórico. Este artigo estabelece essa fronteira explicitamente, de um arquivo de captura a um conjunto de dados que outro analista pode inspecionar.

Defina a Observação Antes do Agendamento

Um snapshot é o resultado salvo de uma solicitação de pesquisa configurada. Inclui a entrada enviada e a resposta recebida pelo cliente. Não estabelece tudo o que cada usuário viu para essa consulta.

Anote o escopo do conjunto de dados antes de agendar a coleta. Escolha uma lista de consultas, contexto de mercado, idioma, tipo de resultado e política de paginação. Atribua cada consulta a um tópico de pesquisa para que um relatório posterior possa explicar por que a consulta foi incluída. Uma pequena amostra revisada é mais fácil de interpretar do que uma grande coleta cujo propósito muda a cada semana.

Separe o cronograma de coleta do contexto de pesquisa. O contexto identifica quais observações podem ser comparadas; os timestamps identificam quando a aplicação as solicitou e recebeu. Um timestamp de recebimento do cliente não é uma afirmação sobre o momento exato em que o Google gerou a página.

Mantenha Registros Brutos e Linhas Derivadas

O registro bruto deve manter a solicitação, a resposta e o estado de coleta. Uma linha de resultado derivada deve apontar de volta para esse registro através de um identificador de execução estável.

Mantenha campos como position, title, link, e snippet na projeção de resultado orgânico quando disponíveis. Também mantenha a ordem do array como um campo separado se você precisar preservar a ordem da fonte. Uma posição retornada ausente deve permanecer ausente; um índice de array não deve substituí-la silenciosamente.

O modelo de dados JSON dá a arrays, objetos e nulo significados diferentes. Preserve essas distinções no arquivo mesmo que a camada de relatório use uma tabela mais simples posteriormente. A resposta bruta torna possível alterar um mapeamento sem recolher uma observação que não pode mais ser reproduzida.

Armazene a versão do parser com dados derivados. Quando um parser é corrigido, regenere a projeção afetada e marque a nova versão. Tratar uma atualização de parser como uma mudança de mercado criaria uma tendência falsa.

Pré-requisitos para um Arquivo de Captura

Use Python com o pacote requests instalado e uma chave de API Scrapeless fornecida através de SCRAPELESS_API_KEY. Instale o cliente com python3 -m pip install requests. As importações restantes usam a biblioteca padrão.

Salve o script abaixo como capture_snapshot.py e execute python3 capture_snapshot.py. Ele escreve um arquivo JSON com nome único sob snapshots. Certifique-se de que esse diretório seja gravável e incluído em sua política de armazenamento. O exemplo é um programa de captura local; ele não fornece um agendador, banco de dados ou serviço de recuperação de resultados de tarefas.

Uma execução autenticada requer sua própria chave de conta. Nenhum resultado de conta ativa é reivindicado aqui. A interface de solicitação foi verificada em relação ao atual fluxo de trabalho de solicitação de pesquisa do Google; o manuseio do arquivo e do estado circundante pode ser testado localmente.

Capture a Solicitação e Seu Estado de Processamento

O programa de captura envia actor: scraper.google.search com as configurações de busca dentro de input. A autenticação usa o cabeçalho x-api-token.

Nota: Este bloco requer SCRAPELESS_API_KEY e acesso ao serviço. Ele não foi executado em uma conta ativa para este artigo. Respostas de tarefas pendentes são salvas para inspeção; a recuperação de resultados de tarefas está fora deste exemplo.

import json
import os
import uuid
from datetime import datetime, timezone
from pathlib import Path
import requests

def capture(input_parameters, directory="snapshots"):
    key = os.environ["SCRAPELESS_API_KEY"]
    request = {"actor": "scraper.google.search", "input": input_parameters}
    record = {
        "schema_version": 1,
        "run_id": str(uuid.uuid4()),
        "requested_at": datetime.now(timezone.utc).isoformat(),
        "request": request,
    }
    try:
        response = requests.post(
            "https://api.scrapeless.com/api/v1/scraper/request",
            headers={"x-api-token": key}, json=request, timeout=120,
        )
        record["http_status"] = response.status_code
        record["received_at"] = datetime.now(timezone.utc).isoformat()
        try:
            payload = response.json()
        except ValueError:
            payload = None
            record["response_text"] = response.text
        record["response"] = payload
        organic = payload.get("organic_results") if isinstance(payload, dict) else None
        if response.status_code == 201:
            record["state"] = "pending"
        elif response.status_code != 200:
            record["state"] = "http_error"
        elif not isinstance(organic, list) or any(not isinstance(x, dict) for x in organic):
            record["state"] = "unmapped"
        else:
            record["state"] = "observed" if organic else "empty"
    except requests.RequestException as exc:
        record["state"] = "transport_error"
        record["error_type"] = type(exc).__name__
    root = Path(directory)
    root.mkdir(parents=True, exist_ok=True)
    path = root / (record["run_id"] + ".json")
    with path.open("x", encoding="utf-8") as handle:
        json.dump(record, handle, ensure_ascii=False, indent=2)
    print(path, record["state"])
    return path

if __name__ == "__main__":
    capture({"q": "coffee", "gl": "us", "hl": "en", "start": 0,
             "google_domain": "google.com", "device": "desktop"})

O script registra o registro após a operação HTTP, incluindo resultados de erro que são úteis para a cobertura da coleta. Seu registro de exceção contém o tipo de exceção ao invés de uma string de diagnóstico completa que poderia expor detalhes desnecessários da solicitação. Armazene as chaves separadamente dos dados de busca arquivados.

O 120 timeout é uma escolha da aplicação. Não é uma garantia de tempo de resposta do serviço. Os timestamps cientes do fuso horário do Python tornam os horários do cliente explícitos; use a mesma convenção quando outro coletor escrever no conjunto de dados.

Comece a Coletar com Scrapeless

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

Reclame seu crédito gratuito agora no Painel do Scrapeless.

Tratar Coleta Ausente como Seu Próprio Resultado

Uma observação falhada não significa que um domínio rastreado desapareceu. O campo de estado protege o relatório desse erro.

observed significa que uma resposta de dados bem-sucedida continha um array orgânico não vazio de objetos. empty significa que o array estava presente e vazio. unmapped significa que a resposta bem-sucedida não correspondia àquela forma mínima. Estes são rótulos da aplicação, não códigos de status da API adicionais.

pending registra o estado da tarefa HTTP 201 documentado. Mantenha o identificador da tarefa retornado com a resposta bruta e use um fluxo de trabalho de recuperação de resultados verificado separadamente antes de contar aquele run como observado. Erros HTTP e erros de transporte pertencem ao relatório de coleta, não a um gráfico de movimento de classificação.

Ao preparar uma visão semanal, mostre quantas observações planejadas foram utilizáveis. Mantenha uma lista de runs ausentes ou não resolvidos ao lado da comparação de resultados. Um gráfico que exclui silenciosamente a coleta falhada pode parecer estável enquanto suas evidências se tornam mais finas.

Comparar Resultados Orgânicos Semelhantes

Uma chave de comparação deve incluir todas as configurações de busca enviadas que podem afetar a observação. A implementação conservadora mais simples serializa todo o objeto de solicitação com chaves ordenadas, excluindo apenas timestamps da aplicação e identificadores de run.

As opções de serialização JSON determinísticas do Python suportam chaves de dicionário ordenadas. Isso dá à sua aplicação uma representação repetível das configurações enviadas. Não prova que configurações diferentes são semanticamente equivalentes, e não congela o comportamento de busca upstream.

Mantenha start na chave ao comparar fatias de página. Se o relatório combinar várias páginas em uma única janela de coleta, defina essa janela de nível superior separadamente e marque páginas ausentes. Não misture uma observação da primeira página com uma coleta mais profunda e chame a diferença de ganho de classificação.

Use as posições orgânicas retornadas apenas dentro da interpretação suportada pela sua resposta coletada. Mantenha os módulos de imagem, local e outros separados. As regras de medição de posição do Search Console descrevem um sistema de relatórios diferente; uma posição da API amostrada não deve ser renomeada como a posição média do Search Console.

Criar um Registro de Mudanças Revisável

Um registro de mudança útil identifica a run antiga, a nova run, o contexto, a URL afetada e a regra que detectou a mudança. Deve descrever uma observação antes de sugerir uma causa.

Para um domínio, diferencie “presente em ambas as fatias capturadas”, “novamente observado nesta fatia” e “não observado na fatia posterior.” O último rótulo é mais restrito do que “removido do Google.” O domínio pode estar fora da profundidade coletada, e uma substituição de URL pode deixar a presença do domínio inalterada.

Para uma URL, mantenha tanto comparações de link exato quanto de host normalizado. A normalização pode ajudar a agrupar páginas, mas a remoção de caminhos, parâmetros ou subdomínios também pode unir aspectos que a pesquisa se preocupa. Documente cada regra de normalização e mantenha o link original ao lado do valor derivado.

Roteie mudanças para revisão humana com as evidências salvas. Atualizações de página, contexto de consulta e mudanças mais amplas na busca podem todos merecer investigação. Um par de snapshots sozinho não pode estabelecer qual deles causou o movimento.

Conclusão

Comece o conjunto de dados com um escopo explícito e um registro de captura bruta. Adicione linhas orgânicas derivadas somente depois que o estado da run for entendido, então compare registros cujas configurações de solicitação correspondam. O resultado é uma história que sua equipe pode auditar, com lacunas de coleta visíveis em vez de convertidas em alegações de classificação.
Um tutorial de coleta de busca em Python fornece informações adicionais; use a interface de solicitação atual mostrada aqui para este conjunto de dados.

Construa Sua Próxima Observação de Busca

Configure a API de Busca do Google em torno das perguntas que sua equipe precisa responder. Verifique os preços do Scrapeless antes de definir a frequência de coleta. O modelo de parâmetros da API de Busca do Google explica os controles de contexto usados neste fluxo de trabalho.

Discuta sua implementação com a comunidade no Discord ou Telegram.

FAQ

P: Isso recupera classificações históricas do Google de antes da coleta começar?

Não. Este fluxo de trabalho constrói a história a partir das observações que você salva. Ele não cria instantâneas anteriores nem fornece um banco de dados de classificações históricas.

P: Um array orgânico vazio é o mesmo que uma solicitação falhada?

Não. Um array vazio presente é registrado como empty; falhas HTTP, falhas de transporte, tarefas pendentes e uma resposta não mapeada possuem estados separados.

P: Países diferentes podem compartilhar a mesma história de classificação?

Eles podem compartilhar um sistema de armazenamento, mas devem permanecer grupos de comparação separados. O país é parte do contexto da solicitação.

P: A posição de um resultado mede visitas ou receita?

Não. Ela descreve a observação de busca retornada. O tráfego e os resultados comerciais precisam de suas próprias evidências e definições correspondentes.

P: Com que frequência as instantâneas devem ser coletadas?

Escolha uma cadência que corresponda à pergunta de pesquisa, orçamento e capacidade de revisão. Registre observações perdidas e evite implicar que um cronograma amostral captura toda mudança.