Loading Light/Dark Toggle
De volta ao blog

Paginação da API do Google SERP: Coletar resultados com start

Alex Johnson
Alex Johnson

Senior Web Scraping Engineer

12-Nov-2026

Resumo:

  • A paginação da pesquisa na web do Google usa offsets de início. Mantenha a consulta e o locale fixos enquanto solicita os offsets 0, 10, 20 e em diante.
  • Dez páginas não implicam cem resultados orgânicos. Uma coleta trabalhada de coffee retornou 95 registros ao longo de dez páginas.
  • Deduplicação precisa de uma definição explícita. Esses 95 registros continham 85 strings de link retornadas distintas, não 85 páginas de destino verificadamente únicas.
  • Um loop limitado precisa de um motivo de parada registrado. Arrays vazios, páginas repetidas, erros e o limite de páginas representam resultados diferentes.

Introdução: Coletar Mais do que a Primeira Página

A paginação da API de SERP do Google é uma sequência de observações relacionadas. Cada requisição pede outro offset da mesma pesquisa, e cada resposta precisa de seu próprio contexto.

Este tutorial usa a Scrapeless Google Search API para solicitar até dez páginas de pesquisa na web. Ele preserva cada resposta, mantém o offset ao lado de cada registro retido e distingue linhas brutas de strings de link deduplicadas. O exemplo é útil para descoberta mais profunda de tópicos e inspeção da cobertura de pesquisa. Ele não estabelece um conjunto de dados completo de ranking dos cem primeiros resultados.

Os controles do endpoint do Google Search definem os offsets de pesquisa na web, enquanto o padrão de requisição do ator explica a chamada de API envolvente. Mantenha o modo de pesquisa fixo durante toda a coleta.

Como start Altera a Requisição

O parâmetro start seleciona o offset dos resultados para uma requisição de pesquisa na web. A sequência de páginas usual é 0, 10, 20 e assim por diante.

O offset é um controle da requisição, não uma contagem de quantos registros orgânicos a resposta anterior devolveu. Se uma página retorna nove registros orgânicos, a próxima requisição neste exemplo ainda usa o próximo offset configurado. Avançar em len(organic_results) misturaria a contagem de respostas com o contrato de paginação.

Mantenha q, gl, hl e quaisquer filtros explícitos inalterados. Se você mudar o país no meio de uma execução, o array combinado deixa de descrever uma única configuração de pesquisa. Armazene o objeto de entrada completo com cada página para que esse erro permaneça detectável.

O exemplo omite num e tbm. É um exemplo de paginação de pesquisa na web; outros modos precisam ser verificados separadamente. Consulte as definições atuais dos parâmetros em vez de transferir offsets entre modos.

Um Exemplo de Dez Páginas com Tamanhos de Página Irregulares

Uma coleta para q=coffee, gl=us e hl=en retornou registros orgânicos em todos os dez offsets solicitados. Cada requisição foi concluída com HTTP 200 nesta amostra.

start Registros Orgânicos Retornados
0 9
10 9
20 9
30 9
40 10
50 10
60 10
70 9
80 10
90 10
Total 95

Igualdade exata das strings link retornadas produziu 85 valores distintos. Esse cálculo não segue redirecionamentos, não compara tags canônicas nem estabelece identidade de conteúdo. Dois links diferentes podem levar a uma página; duas páginas diferentes também podem compartilhar um domínio. Nem o agrupamento por hostname nem a comparação bruta de strings comprovam cobertura única de destinos.

Este exemplo estabelece que os offsets configurados retornaram dados em uma coleta. Não é uma garantia de que toda consulta exponha dez páginas não vazias. Os resultados de pesquisa podem mudar enquanto uma coleta com múltiplas requisições está em execução.

Construir um Coletor de Paginação Limitado

O coletor faz no máximo dez submissões de pesquisa, salva cada resposta concluída e para mais cedo quando encontra um array orgânico vazio ou uma página de resultados idêntica. Ele registra um erro como erro e mantém os dados já coletados.

Os pré-requisitos são Python, Requests e SCRAPELESS_API_KEY definido no ambiente. Instale Requests com python -m pip install requests, salve o programa como paginate_google.py e execute python paginate_google.py. A saída vai para um novo diretório em pagination-runs.
O auxiliar de requisições lida tanto com tarefas concluídas quanto pendentes. Ele envia cada busca uma única vez e usa o endpoint de resultado da tarefa existente quando necessário. O fluxo de trabalho de tarefas pendentes define essa distinção; os limites do código são escolhas de política local.

python Copy
import json
import os
import time
from pathlib import Path
from urllib.parse import quote

import requests

BASE = "https://api.scrapeless.com/api/v1/scraper"


def google_search(query):
    headers = {"x-api-token": os.environ["SCRAPELESS_API_KEY"]}
    response = requests.post(
        BASE + "/request", headers=headers,
        json={"actor": "scraper.google.search", "input": query},
        timeout=(10, 60), allow_redirects=False,
    )
    task_id = None
    for poll in range(11):
        response.raise_for_status()
        if response.status_code not in (200, 201):
            raise RuntimeError(f"Unexpected HTTP status: {response.status_code}")
        data = response.json()
        if not isinstance(data, dict):
            raise ValueError("Expected a JSON object")
        if response.status_code == 200:
            return data
        if task_id is None:
            task_id = data.get("taskId")
        if not isinstance(task_id, str) or not task_id:
            raise ValueError("Pending response has no taskId")
        if poll == 10:
            raise TimeoutError(f"Task still pending; retain taskId={task_id}")
        time.sleep(2)
        response = requests.get(
            BASE + "/result/" + quote(task_id, safe=""),
            headers=headers, timeout=(10, 30), allow_redirects=False,
        )


def organic_rows(data):
    rows = data.get("organic_results")
    if not isinstance(rows, list):
        raise ValueError("organic_results is missing or is not an array")
    if not all(isinstance(row, dict) for row in rows):
        raise ValueError("organic_results contains a non-object item")
    return rows


if __name__ == "__main__":
    from datetime import datetime, timezone
    run_dir = Path("pagination-runs") / datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%fZ")
    run_dir.mkdir(parents=True)
    seen_links = set()
    seen_pages = set()
    collected = []
    summary = []
    stop_reason = "page_limit"
    try:
        for start in range(0, 100, 10):
            query = {"q": "coffee", "gl": "us", "hl": "en", "start": start}
            data = google_search(query)
            (run_dir / f"page-{start}.json").write_text(
                json.dumps({"input": query, "response": data}, ensure_ascii=False, indent=2),
                encoding="utf-8",
            )
            rows = organic_rows(data)
            signature = json.dumps(rows, sort_keys=True, ensure_ascii=False)
            repeat = bool(rows) and signature in seen_pages
            seen_pages.add(signature)
            new_count = 0
            for index, row in enumerate(rows, start=1):
                link = row.get("link")
                usable_link = isinstance(link, str) and bool(link.strip())
                if usable_link and link in seen_links:
                    continue
                if usable_link:
                    seen_links.add(link)
                collected.append({"start": start, "array_index": index, "result": row})
                new_count += 1
            summary.append({"start": start, "returned": len(rows), "kept": new_count})
            if not rows:
                stop_reason = "empty_organic_array"
                break
            if repeat:
                stop_reason = "identical_result_page"
                break
    except (requests.RequestException, ValueError, RuntimeError, TimeoutError) as exc:
        stop_reason = "error:" + type(exc).__name__
        raise
    finally:
        (run_dir / "collected.json").write_text(json.dumps(collected, ensure_ascii=False, indent=2), encoding="utf-8")
        report = {"pages": summary, "stop_reason": stop_reason, "kept_rows": len(collected)}
        (run_dir / "summary.json").write_text(json.dumps(report, indent=2), encoding="utf-8")
        print(json.dumps(report))

O bloco finally grava um resumo mesmo que uma página posterior falhe. Uma página com falha não é adicionada como uma página vazia. Os arquivos de páginas salvos anteriormente continuam disponíveis para inspeção, e a exceção lançada ainda faz o programa falhar de forma visível.

Comece a Fazer Scraping com o Scrapeless

Potencialize o seu fluxo de trabalho de web scraping e automação com o Scrapeless!
Cadastre-se hoje e ganhe US$ 5 em crédito grátis — sem necessidade de cartão de crédito.

Resgate seu crédito gratuito agora no Scrapeless Dashboard.

Escolha Regras Conservadoras de Desduplicação

O coletor desduplica exatamente as strings de links retornados não vazios e mantém linhas com links ausentes. Essa política é fácil de auditar porque não reescreve componentes de URL.

O modelo de normalização de URI explica por que a comparação de URLs exige regras explícitas. Excluir cegamente query strings, alterar maiúsculas e minúsculas do caminho ou colapsar variantes de barra pode apagar distinções significativas. Adicione normalização mais forte somente depois de validar os sites de destino envolvidos.

Todos os registros brutos de página permanecem nos arquivos de página, mesmo quando a saída combinada mantém apenas a primeira ocorrência de um link repetido. Para análise de ocorrência, leia esses arquivos de página em vez da coleção desduplicada. Caso contrário, você perderia a evidência de que um link apareceu em mais de um deslocamento.

A proteção contra páginas repetidas compara registros de resultado serializados. Ela detecta dados exatamente repetidos; não afirma identificar todo SERP quase duplicado. Um limite de páginas delimitado continua necessário porque pequenas mudanças de campo podem fazer duas respostas visualmente semelhantes serem comparadas como diferentes.

Interprete Páginas Vazias e Execuções Parciais

Um array orgânico vazio é uma condição de parada neste coletor, não prova de que o Google não tem mais páginas indexadas sobre o tópico. Arrays ausentes e registros malformados continuam sendo falhas de validação.

Motivo de Parada O que o Coletor Observou Interpretação Segura
page_limit O orçamento de páginas configurado foi atingido A coleta está completa em relação ao seu orçamento configurado
empty_organic_array Uma resposta concluída tinha zero registros orgânicos Esta execução parou naquele deslocamento
identical_result_page Os registros orgânicos se repetiram exatamente A coleta posterior foi interrompida pela proteção
error:... Uma etapa de requisição ou parsing falhou O conjunto de dados é parcial

A semântica geral de status HTTP ajuda a distinguir resultados de transporte, enquanto sua aplicação ainda deve registrar a completude da coleta. Uma primeira página bem-sucedida não torna bem-sucedida uma página posterior com falha.

Para trabalho agendado, atribua um identificador de execução e mantenha carimbos de tempo, entradas, deslocamentos e motivos de parada. Isso segue o propósito prático de proveniência de dados: consumidores posteriores devem ser capazes de rastrear um conjunto de dados derivado de volta às observações e transformações que o produziram.

Conclusão: Relate Profundidade e Cobertura Separadamente

Um relatório de paginação deve mostrar deslocamentos solicitados, páginas concluídas, linhas brutas e a regra de desduplicação. Essas medições respondem a perguntas diferentes e devem permanecer separadas tanto no código quanto na redação.

Use a página do produto Google Search API para detalhes do serviço e preços atuais ao planejar orçamentos para coletas mais profundas. Um orçamento de dez páginas é uma configuração de coleta, não uma promessa de cem URLs finais.

Construa Seu Fluxo de Trabalho de Dados de Busca

Junte-se aos desenvolvedores que trabalham com dados de busca em nossa comunidade: Discord · Telegram.

Crie uma conta Scrapeless e aplique este tutorial a um pequeno conjunto de consultas antes de agendar uma coleta maior.

FAQ

P: O parâmetro start deve aumentar pelo número de linhas retornadas?
Não. Siga a sequência de deslocamento de pesquisa na web. Uma página com nove resultados orgânicos não altera o próximo deslocamento configurado.

P: Uma coleção de dez páginas sempre retorna cem resultados?

Não. A coleção processada retornou 95 resultados orgânicos. O tamanho da página e a disponibilidade devem ser medidos a partir de cada resposta.

P: 85 strings de link distintos são o mesmo que 85 páginas da web únicas?

Não. A deduplicação exata de strings não verifica redirecionamentos, identidade canônica ou conteúdo da página.

P: Um erro HTTP deve ser armazenado como uma página vazia?

Não. Armazene a falha separadamente e marque a execução como parcial. Um array vazio concluído tem um significado diferente.

P: pagination.next precisa ser buscado diretamente no Google?

Não. Este cliente mantém as requisições no endpoint do Scrapeless e fornece o valor configurado start. Ele não busca diretamente as URLs de navegação do Google.

P: O coletor pode ser executado sem um agente de IA?

Sim. É um programa Python independente com um loop sequencial de páginas delimitado.

Na Scorretless, acessamos apenas dados disponíveis ao público, enquanto cumprem estritamente as leis, regulamentos e políticas de privacidade do site aplicáveis. O conteúdo deste blog é apenas para fins de demonstração e não envolve atividades ilegais ou infratoras. Não temos garantias e negamos toda a responsabilidade pelo uso de informações deste blog ou links de terceiros. Antes de se envolver em qualquer atividade de raspagem, consulte seu consultor jurídico e revise os termos de serviço do site de destino ou obtenha as permissões necessárias.

Artigos mais populares

Catálogo