Loading Light/Dark Toggle
Volver al blog

Paginación de la API de SERP de Google: recopila resultados con start

Alex Johnson
Alex Johnson

Senior Web Scraping Engineer

12-Nov-2026

TL;DR:

  • La paginación de la búsqueda web de Google usa offsets de inicio. Mantén la consulta y la configuración regional fijas mientras solicitas los offsets 0, 10, 20 y siguientes.
  • Diez páginas no implican cien resultados orgánicos. Una recopilación trabajada de coffee devolvió 95 registros en diez páginas.
  • La deduplicación necesita una definición explícita. Esos 95 registros contenían 85 cadenas de enlace devueltas distintas, no 85 páginas de destino únicas verificadas.
  • Un bucle acotado necesita un motivo de parada registrado. Arreglos vacíos, páginas repetidas, errores y el límite de páginas representan resultados diferentes.

Introducción: recopila más que la primera página

La paginación del API de SERP de Google es una secuencia de observaciones relacionadas. Cada solicitud pide otro offset de la misma búsqueda, y cada respuesta necesita su propio contexto.

Este tutorial utiliza Scrapeless Google Search API para solicitar hasta diez páginas de búsqueda web. Conserva cada respuesta, mantiene el offset junto a cada registro retenido y distingue las filas en bruto de las cadenas de enlace deduplicadas. El ejemplo es útil para un descubrimiento de temas más profundo y la inspección de la cobertura de búsqueda. No establece un conjunto de datos completo de ranking del top cien.

Los controles del endpoint de Google Search definen los offsets de búsqueda web, mientras que el patrón de solicitud del actor explica la llamada de API que lo rodea. Mantén fijo el modo de búsqueda durante toda la recopilación.

Cómo start cambia la solicitud

El parámetro start selecciona el offset de resultados para una solicitud de búsqueda web. La secuencia de páginas habitual es 0, 10, 20, y así sucesivamente.

El offset es un control de la solicitud, no un recuento de cuántos registros orgánicos contenía la respuesta anterior. Si una página devuelve nueve registros orgánicos, la siguiente solicitud en este ejemplo sigue usando el siguiente offset configurado. Avanzar en len(organic_results) mezclaría el recuento de la respuesta con el contrato de paginación.

Mantén q, gl, hl y cualquier filtro explícito sin cambios. Si cambias el país a mitad de una ejecución, el arreglo combinado deja de describir una única configuración de búsqueda. Almacena el objeto de entrada completo con cada página para que este error siga siendo detectable.

El ejemplo omite num y tbm. Es un ejemplo de paginación de búsqueda web; otros modos deben revisarse por separado. Consulta las definiciones actuales de parámetros en lugar de transferir offsets entre modos.

Un ejemplo de diez páginas con tamaños de página desiguales

Una recopilación para q=coffee, gl=us y hl=en devolvió registros orgánicos en los diez offsets solicitados. Cada solicitud se completó con HTTP 200 en esta muestra.

start Registros orgánicos devueltos
0 9
10 9
20 9
30 9
40 10
50 10
60 10
70 9
80 10
90 10
Total 95

La igualdad exacta de las cadenas link devueltas produjo 85 valores distintos. Ese cálculo no sigue redirecciones, no compara etiquetas canónicas ni establece identidad de contenido. Dos enlaces diferentes pueden llevar a una misma página; dos páginas diferentes también pueden compartir un dominio. Ni la agrupación por nombre de host ni la comparación de cadenas en bruto prueban una cobertura única de destinos.

Este ejemplo establece que los offsets configurados devolvieron datos en una recopilación. No es una garantía de que cada consulta exponga diez páginas no vacías. Los resultados de búsqueda pueden cambiar mientras se ejecuta una recopilación con varias solicitudes.

Crea un recolector de paginación acotado

El recolector realiza como máximo diez envíos de búsqueda, guarda cada respuesta completada y se detiene antes cuando ve un arreglo orgánico vacío o una página de resultados idéntica. Registra un error como error y conserva los datos ya recopilados.

Los requisitos previos son Python, Requests y SCRAPELESS_API_KEY definido en el entorno. Instala Requests con python -m pip install requests, guarda el programa como paginate_google.py y ejecuta python paginate_google.py. La salida va a un nuevo directorio bajo pagination-runs.
El asistente de solicitudes maneja tanto tareas completadas como pendientes. Envía cada búsqueda una vez y utiliza el endpoint de resultados de la tarea existente cuando es necesario. El flujo de trabajo de tareas pendientes define esa distinción; los límites del código son decisiones 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))

El bloque finally escribe un resumen incluso si una página posterior falla. Una página fallida no se agrega como una página vacía. Los archivos de páginas guardados anteriormente siguen disponibles para su inspección, y la excepción generada aún hace que el programa falle de forma visible.

Empieza a hacer scraping con Scrapeless

Potencia tu flujo de trabajo de web scraping y automatización con Scrapeless.
Regístrate hoy y obtén 5 USD en crédito gratuito — sin necesidad de tarjeta de crédito.

Reclama tu crédito gratuito ahora en el Scrapeless Dashboard.

Elige reglas de desduplicación conservadoras

El recolector desduplica exactamente las cadenas de enlaces devueltas no vacías y conserva las filas con enlaces faltantes. Esa política es fácil de auditar porque no reescribe componentes de la URL.

El modelo de normalización de URI explica por qué la comparación de URL requiere reglas explícitas. Eliminar a ciegas las cadenas de consulta, cambiar las mayúsculas/minúsculas de la ruta o colapsar variantes de barras puede borrar distinciones significativas. Añade una normalización más estricta solo después de validar los sitios web de destino involucrados.

Todos los registros de página sin procesar permanecen en los archivos de página, incluso cuando la salida combinada conserva solo la primera aparición de un enlace repetido. Para análisis de ocurrencias, lee esos archivos de página en lugar de la colección desduplicada. De lo contrario, perderías la evidencia de que un enlace apareció en más de un desplazamiento.

La salvaguarda de páginas repetidas compara los registros de resultados serializados. Detecta datos repetidos exactamente; no pretende identificar todos los SERP casi duplicados. Sigue siendo necesario un límite acotado de páginas porque pequeños cambios de campos pueden hacer que dos respuestas visualmente similares se comparen de forma diferente.

Interpreta páginas vacías y ejecuciones parciales

Un array orgánico vacío es una condición de parada en este recolector, no prueba de que Google no tenga más páginas indexadas sobre el tema. Los arrays faltantes y los registros mal formados siguen siendo fallos de validación.

Motivo de parada Lo que observó el recolector Interpretación segura
page_limit Se alcanzó el presupuesto de páginas configurado La colección está completa según su presupuesto configurado
empty_organic_array Una respuesta completada tenía cero registros orgánicos Esta ejecución se detuvo en ese desplazamiento
identical_result_page Los registros orgánicos se repitieron exactamente La recopilación posterior fue detenida por la salvaguarda
error:... Falló una solicitud o un paso de análisis El conjunto de datos es parcial

Las semánticas generales de estados HTTP ayudan a distinguir los resultados de transporte, mientras que tu aplicación todavía debe registrar la integridad de la colección. Una primera página exitosa no hace exitosa una página posterior fallida.

Para trabajo programado, asigna un identificador de ejecución y conserva marcas de tiempo, entradas, desplazamientos y motivos de parada. Esto sigue el propósito práctico de la procedencia de datos: los consumidores posteriores deberían poder rastrear un conjunto de datos derivado hasta las observaciones y transformaciones que lo produjeron.

Conclusión: informa profundidad y cobertura por separado

Un informe de paginación debería mostrar desplazamientos solicitados, páginas completadas, filas en bruto y la regla de desduplicación. Esas mediciones responden a preguntas diferentes y deberían seguir estando separadas tanto en el código como en el texto.

Usa la página de producto de Google Search API para detalles del servicio y los precios actuales al presupuestar colecciones más profundas. Un presupuesto de diez páginas es una configuración de colección, no una promesa de cien URL finales.

Crea tu flujo de trabajo de datos de búsqueda

Únete a los desarrolladores que trabajan con datos de búsqueda en nuestra comunidad: Discord · Telegram.

Crea una cuenta de Scrapeless y aplica este tutorial a un conjunto pequeño de consultas antes de programar una colección más grande.

Preguntas frecuentes

P: ¿Debería start aumentar en el número de filas devueltas?
No. Siga la secuencia de desplazamiento de búsqueda web. Una página con nueve resultados orgánicos no cambia el siguiente desplazamiento configurado.

P: ¿Una colección de diez páginas siempre devuelve cien resultados?

No. La colección trabajada devolvió 95 resultados orgánicos. El tamaño de página y la disponibilidad deben medirse a partir de cada respuesta.

P: ¿85 cadenas de enlace distintas son lo mismo que 85 páginas web únicas?

No. La desduplicación exacta de cadenas no verifica redirecciones, identidad canónica ni contenido de la página.

P: ¿Se debe almacenar un error HTTP como una página vacía?

No. Almacene el fallo por separado y marque la ejecución como parcial. Un array vacío completado tiene un significado diferente.

P: ¿Es necesario obtener pagination.next directamente de Google?

No. Este cliente mantiene las solicitudes en el endpoint de Scrapeless y proporciona el valor configurado de start. No obtiene directamente las URL de navegación de Google.

P: ¿El recolector puede ejecutarse sin un agente de IA?

Sí. Es un programa independiente de Python con un bucle de páginas secuencial acotado.

En Scrapeless, solo accedemos a datos disponibles públicamente y cumplimos estrictamente con las leyes, regulaciones y políticas de privacidad del sitio web aplicables. El contenido de este blog es sólo para fines de demostración y no implica ninguna actividad ilegal o infractora. No ofrecemos garantías y renunciamos a toda responsabilidad por el uso de la información de este blog o enlaces de terceros. Antes de realizar cualquier actividad de scraping, consulte a su asesor legal y revise los términos de servicio del sitio web de destino u obtenga los permisos necesarios.

Artículos más populares

Catalogar