Loading Light/Dark Toggle
Volver al blog

Tutorial de la API de Búsqueda de Google en Python: Solicitudes y Resultados

Alex Johnson
Alex Johnson

Senior Web Scraping Engineer

12-Nov-2026

Resumen rápido:

  • La API de búsqueda de Google de Scrapeless devuelve datos de búsqueda estructurados a Python. Envía q, gl y hl en una solicitud JSON autenticada.
  • HTTP 200 y HTTP 201 requieren un manejo diferente. Lee un resultado completado directamente; conserva un ID de tarea pendiente y recupera esa tarea existente.
  • Una respuesta HTTP exitosa aún necesita una verificación de datos. Valida organic_results antes de usar las filas.
  • Conservar la respuesta facilita el análisis posterior. Guarda el JSON antes de seleccionar títulos, fragmentos o enlaces.

Introducción: hacer que un resultado de búsqueda sea utilizable en Python

Una solicitud de búsqueda solo es útil para una aplicación cuando la aplicación puede distinguir los datos completados de una tarea que aún se está ejecutando. Un script rápido que imprime response.text te pone en marcha, pero deja esos estados mezclados.

Este tutorial de la API de búsqueda de Google en Python construye un pequeño cliente para la API de búsqueda de Google de Scrapeless. Configurarás una consulta, la enviarás, manejarás una tarea pendiente y guardarás una respuesta que otro script pueda inspeccionar. El ejemplo utiliza la búsqueda web ordinaria. Imágenes, Local, Videos y Shopping tienen secciones de resultados diferentes y necesitan su propia validación.

El código se comunica con Scrapeless; no es la API JSON de Búsqueda personalizada de Google ni la API de Search Console. Tu aplicación recibe una instantánea de búsqueda en lugar de los informes de tráfico de tu sitio. Si ya trabajas con el modelo de solicitud de actor más amplio de Scrapeless, el sobre de la solicitud te resultará familiar.

Requisitos previos

Necesitas Python, el paquete requests y una clave de API de Scrapeless con acceso al servicio. Usa un entorno virtual para el proyecto e instala Requests con python -m pip install requests. Define SCRAPELESS_API_KEY en el entorno de tu proceso antes de ejecutar el script. Mantén la clave fuera de los archivos fuente, cuadernos que compartas y registros de respuestas.

La variable de entorno local es una convención elegida para este script. La cabecera de autenticación HTTP es x-api-token. Tienen trabajos diferentes: Python lee la variable y luego envía su valor en la cabecera al endpoint de la API.

Guarda el programa completo que aparece a continuación como google_search.py y ejecútalo con python google_search.py. El programa crea serp.json en el directorio de trabajo. Usa un directorio separado para cada experimento si quieres conservar las respuestas anteriores.

Configurar q, gl y hl

El parámetro q proporciona la consulta de búsqueda, gl selecciona el país de búsqueda y hl selecciona el idioma de búsqueda. Estos controles pertenecen dentro de input, junto al nombre del actor en el objeto de solicitud que lo rodea.

Field Example What to Check
actor scraper.google.search Mantén el actor en el nivel superior
input.q coffee Conserva exactamente la consulta que pretendes comparar
input.gl us Registra el país solicitado junto con el resultado
input.hl en Registra el idioma solicitado por separado

Empieza con esta pequeña entrada. Agregar filtros de localización y búsqueda hace que sea más difícil identificar inmediatamente qué parámetro cambió una salida. Mantén a mano los parámetros actuales de Búsqueda de Google cuando amplíes la solicitud.

Envía el cuerpo con el argumento json= de Requests. Este serializa el objeto de Python como JSON y establece el tipo de contenido apropiado. Los objetos y arreglos JSON son estructuras distintas en el formato de datos JSON; una respuesta que se analiza correctamente no es automáticamente la forma de objeto que tu aplicación espera.

Enviar una solicitud y recuperar una tarea pendiente

El cliente envía una tarea de búsqueda y luego verifica el endpoint de resultados solo si esa tarea aún se está procesando. Una respuesta completada se devuelve al llamador como un diccionario de Python.

La guía de inicio rápido de Búsqueda de Google utiliza POST /api/v1/scraper/request. Para esta API, HTTP 201 significa que el procesamiento está en curso e incluye taskId. El flujo de trabajo de resultado de tarea recupera ese ID con GET /api/v1/scraper/result/{taskId}.
Esta es una interpretación específica de la aplicación del código de estado. La especificación de semántica HTTP general define clases de estado, mientras que el contrato del servicio le indica a tu cliente cómo manejar una tarea pendiente.

El programa limita las comprobaciones de resultado a diez, con un intervalo de dos segundos. Esas son configuraciones de ejemplo del cliente, no límites del servicio ni un tiempo de finalización garantizado. Los timeouts de red se aplican por separado a cada solicitud. Si la tarea sigue pendiente, la excepción incluye su ID para que un operador pueda conservarla.

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__":
    query = {"q": "coffee", "gl": "us", "hl": "en"}
    try:
        result = google_search(query)
        Path("serp.json").write_text(
            json.dumps(result, ensure_ascii=False, indent=2), encoding="utf-8"
        )
        rows = organic_rows(result)
        print(f"Saved serp.json; organic rows: {len(rows)}")
        for row in rows:
            print(row.get("position"), row.get("title"), row.get("link"))
    except requests.HTTPError as exc:
        raise SystemExit(f"HTTP request failed: {exc.response.status_code}")
    except requests.RequestException:
        raise SystemExit("Network request did not complete")
    except (ValueError, RuntimeError, TimeoutError, KeyError) as exc:
        raise SystemExit(str(exc))

El primer raise_for_status() captura las respuestas de error HTTP. La comprobación explícita del estado también rechaza estados inesperados que no sean de error. El análisis de JSON viene después de esas comprobaciones, y el validador de resultados se ejecuta después de que la API indica que la tarea está completa. Cada etapa responde a una pregunta diferente.

Empieza a hacer scraping con Scrapeless

Potencia tu flujo de trabajo de web scraping y automatización con Scrapeless.
Regístrate hoy y consigue 5 USD de crédito gratis — no se requiere tarjeta de crédito.

Reclama tu crédito gratis ahora en el Panel de Scrapeless.

Leer organic_results sin perder la respuesta original

El arreglo organic_results contiene los registros de resultados orgánicos en la respuesta completada. Lee campos como position, title, snippet y link de cada registro, mientras conservas el objeto original para su inspección.

La solicitud base coffee utilizada al preparar este tutorial devolvió HTTP 200 y ocho registros orgánicos con gl=us y hl=en. Ese conteo describe una respuesta. Una solicitud posterior para la misma consulta puede contener un número diferente de filas o una disposición distinta de funciones de búsqueda.

El programa guarda el JSON antes de validar el arreglo orgánico. Esto importa cuando una respuesta completada tiene una forma inesperada: puedes inspeccionar lo que llegó en lugar de perderlo cuando la validación genera una excepción. La interfaz de codificación y decodificación JSON de Python permite mantener texto no ASCII legible mediante ensure_ascii=False.

Trata tres casos por separado. Un arreglo vacío es una colección observada sin elementos orgánicos. Una clave ausente no tiene esa garantía. Un valor del tipo incorrecto es un problema de esquema. El script acepta el primer caso y se detiene en los otros dos en lugar de reemplazarlos silenciosamente por una lista vacía.

Los enlaces devueltos también necesitan contexto. Una URL que parece directa es una candidata de destino; un intermediario de Google requiere un manejo adicional antes de que la trates como un sitio web objetivo. Este primer tutorial imprime el valor devuelto sin afirmar que se haya verificado el destino final.

Manejar fallos en la capa adecuada

Una excepción debe identificar la etapa que falló sin exponer el encabezado de autenticación ni convertir una solicitud fallida en un resultado vacío que parezca válido.

Observación Significado para este cliente Siguiente inspección
Variable de entorno ausente La autenticación no se configuró localmente Revisa el entorno del proceso
HTTP 400 La API rechazó la solicitud Revisa nombres de entrada, tipos y combinaciones
HTTP 429 El servicio informa un límite de solicitudes Revisa la frecuencia de solicitudes y la cuota de la cuenta
Otro error HTTP No se aceptó ningún resultado completado Conserva el estado y el contexto de la solicitud para investigación
JSON inválido No se pudo analizar el cuerpo Inspecciona la respuesta en un registro de diagnóstico controlado
Arreglo orgánico ausente La carga útil no coincide con este consumidor Inspecciona el JSON guardado y el modo de búsqueda solicitado
Límite de tarea pendiente alcanzado Este cliente no observó la finalización Conserva el ID de la tarea y marca el trabajo como incompleto

El ejemplo evita deliberadamente imprimir encabezados de solicitud completos o cuerpos de error del servidor. En un servicio más grande, escribe diagnósticos estructurados con la configuración de la consulta, el estado y el ID de la tarea cuando esté disponible. Registra una ejecución fallida por separado de las observaciones completadas para que los informes posteriores no confundan fallo con ausencia.

Conclusión: Mantén pequeño el primer cliente

Un cliente útil de la API de Búsqueda de Google en Python tiene un camino claro: enviar una consulta, recuperar la tarea existente si es necesario, conservar la respuesta y validar los campos que consume tu aplicación. Una vez que ese camino funcione, agrega una dimensión de entrada a la vez.
Use los detalles del producto de la Google Search API para elegir el servicio y los precios actuales para planificar la recolección repetida. Mantén la configuración de cada solicitud junto a cada respuesta guardada antes de construir un conjunto de datos más grande.

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 recolección más grande.

Preguntas frecuentes

P: ¿Puede Python llamar a la Google Search API sin un SDK?

Sí. El ejemplo usa Requests y el endpoint HTTP documentado. No requiere un agente de IA ni un SDK específico de un framework.

P: ¿El HTTP 201 contiene el resultado final de la búsqueda?

Para esta API, HTTP 201 indica una tarea pendiente. Conserva taskId y recupera esa tarea a través del endpoint de resultados.

P: ¿gl=us prueba que cada resultado es estadounidense?

No. El país es un parámetro de entrada de búsqueda, no una etiqueta de nacionalidad para cada página devuelta. La precisión local necesita un método de validación independiente.

P: ¿Una clave organic_results ausente debe convertirse en una lista vacía?

No. Una clave ausente y un arreglo explícitamente vacío son observaciones diferentes. Revisa la forma de la respuesta antes de informar que no se devolvieron registros orgánicos.

P: ¿Necesitas configurar un proxy por separado?

Esta solicitud básica no necesita una configuración de proxy por separado. La API se encarga de la recuperación; consulta el contrato de parámetros antes de añadir configuraciones de transporte o de ubicación.

P: ¿El script verifica el contenido detrás de cada enlace de resultado?

No. Recoge una instantánea de la búsqueda. La verificación del destino y la validación del contenido de la página son pasos independientes.

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