Paginação da API do Google SERP: Coletar resultados com start
Senior Web Scraping Engineer
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,20e em diante. - Dez páginas não implicam cem resultados orgânicos. Uma coleta trabalhada de
coffeeretornou 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
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.



