API de Búsqueda de Google: De Consultas de Búsqueda a JSON Estructurado

TL;DR:

• La API de búsqueda de Google sin scrapear devuelve resultados de búsqueda como JSON estructurado. Utiliza campos de resultados orgánicos en herramientas de investigación, informes de SEO y flujos de trabajo de descubrimiento de fuentes.
• El contexto de búsqueda pertenece al resultado. Mantén la consulta, país, idioma y tiempo de observación juntos para que las comparaciones posteriores tengan un significado claro.
• Una tarea pendiente es diferente de un conjunto de resultados vacío. Maneja HTTP 201 por separado antes de intentar leer organic_results o crear un CSV.

Los datos de búsqueda de Google se vuelven útiles cuando un equipo puede conectar cada resultado con la pregunta y el mercado que lo produjeron. Un título y una URL copiados en una hoja de cálculo pierden gran parte de ese contexto. Una respuesta estructurada permite a una aplicación preservar ese contexto desde el principio.

La API de búsqueda de Google sin scrapear actualizada proporciona una ruta administrada desde una consulta de búsqueda a JSON. Tu aplicación envía la solicitud y decide cómo usar los datos devueltos. El manejo de proxy y CAPTCHA se realiza del lado del servicio, reduciendo la infraestructura de recolección que tu equipo necesita mantener.

Esta guía sigue esa entrega: elige un contexto de búsqueda, envía una solicitud, lee la respuesta y guarda un conjunto de datos que otra persona pueda entender.

Lo que la API de Búsqueda de Google Devuelve

La API de Búsqueda de Google devuelve datos de búsqueda estructurados, con resultados orgánicos disponibles en el array de organic_results de nivel superior cuando están presentes. Un resultado natural puede incluir position, title, link y snippet. La respuesta también puede contener información de paginación y otros módulos de búsqueda, dependiendo de la consulta y los resultados devueltos.

Mantén la respuesta original antes de extraer un subconjunto. Una tabla plana es conveniente para el análisis, pero no puede representar cada objeto anidado sin un mapeo deliberado. El modelo de datos JSON distingue entre arrays, objetos, cadenas, números, booleanos y nulos; preservar esas distinciones facilita el procesamiento posterior.

Un fragmento es un extracto de un resultado de búsqueda. No proporciona el contenido completo de la página de destino. Si una aplicación de investigación necesita la evidencia de un artículo, la aplicación debe obtener y revisar esa página por separado.

Prepara una Primera Solicitud Pequeña

Una primera solicitud necesita una clave de API de Scrapeless, una consulta y un cliente que pueda enviar JSON a través de HTTP. Utiliza una cuenta con acceso a la API de Búsqueda de Google y mantén la clave en la variable de entorno SCRAPELESS_API_KEY.

Para el ejemplo en Python a continuación, instala el paquete requests en el entorno de tu proyecto. Los módulos restantes provienen de la biblioteca estándar de Python. Guarda el script como google_search_export.py, luego ejecútalo con python3 google_search_export.py después de configurar la variable de entorno a través de tu terminal local o administrador de secretos.

El ejemplo utiliza la consulta neutral coffee, país us y idioma en. Comienza con esta entrada pequeña antes de introducir una lista de palabras clave o un trabajo programado. Inspecciona primero la forma de la respuesta; el modelo de datos posterior depende de ella.

La solicitud autenticada es un requisito previo que requiere tu propia clave de cuenta. La forma de la solicitud del ejemplo sigue la referencia de la API actual; no se presenta como una ejecución en vivo de cuenta captada.

Elige País, Idioma y Modo de Entrada

El país, el idioma y la ubicación describen diferentes partes de una solicitud de búsqueda. gl selecciona el país de búsqueda, hl selecciona el idioma de búsqueda y location especifica de dónde debería originarse la búsqueda. google_domain selecciona el dominio de Google. La opción de dispositivo actual admite el escritorio.

El modelo de parámetros de la API de Búsqueda de Google también tiene dos reglas de entrada que afectan cómo construyes las solicitudes:

• Usa q para una consulta expresada a través de parámetros individuales. Alternativamente, proporciona una url completa de Búsqueda de Google; cuando se proporciona url, se ignoran otros parámetros de entrada.
• Elige location o uule. No se pueden usar juntos.

Para una comparación entre mercados, guarda el objeto de entrada completo con cada respuesta. Establecer el mismo país e idioma hace que el contexto previsto sea explícito, pero no garantiza resultados idénticos entre observaciones ni reproduce el historial de búsqueda firmado de una persona en particular.
Las consultas pueden incluir operadores como site:, inurl: y intitle:. Úselos para restringir una pregunta de investigación. Una búsqueda restringida por sitio no es un inventario completo de las páginas indexadas, por lo que sus resultados no deben convertirse en un recuento exacto de la cobertura del índice.

Solicitar JSON y Exportar Resultados Orgánicos

La solicitud utiliza POST https://api.scrapeless.com/api/v1/scraper/request, el actor scraper.google.search y un encabezado x-api-token. El script guarda la respuesta con su entrada y hora de recepción, luego exporta los resultados orgánicos a CSV después de HTTP 200.

Nota: La solicitud de red requiere su clave de API Scrapeless y no se ha ejecutado con una cuenta activa para este artículo. El script preserva una respuesta de tarea HTTP 201 para inspección; no implementa la recuperación de resultados de tareas.

import csv
import json
import os
from datetime import datetime, timezone
from pathlib import Path

import requests


def spreadsheet_text(value):
    text = "" if value is None else str(value)
    if text.lstrip().startswith(("=", "+", "-", "@")) or text.startswith(("\t", "\r")):
        return "'" + text
    return text


def export_results(payload, context, received_at, output_path):
    results = payload.get("organic_results")
    if not isinstance(results, list):
        print("No usable organic_results array; inspect the saved JSON.")
        return
    fields = ["q", "gl", "hl", "received_at", "position", "title", "link", "snippet"]
    with output_path.open("w", encoding="utf-8", newline="") as stream:
        writer = csv.DictWriter(stream, fieldnames=fields)
        writer.writeheader()
        for item in results:
            if not isinstance(item, dict):
                raise ValueError("Unexpected organic result item; inspect the saved JSON.")
            row = {name: item.get(name) for name in ("position", "title", "link", "snippet")}
            row.update(context, received_at=received_at)
            writer.writerow({name: spreadsheet_text(row.get(name)) for name in fields})
    print(f"Exported {len(results)} organic results to {output_path}")


def main():
    context = {"q": "coffee", "gl": "us", "hl": "en"}
    response = requests.post(
        "https://api.scrapeless.com/api/v1/scraper/request",
        headers={"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
        json={"actor": "scraper.google.search", "input": context},
        timeout=120,
    )
    response.raise_for_status()
    received_at = datetime.now(timezone.utc).isoformat()
    run_id = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%fZ")
    payload = response.json()
    record = {"input": context, "received_at": received_at,
              "http_status": response.status_code, "response": payload}
    output = Path(f"google-search-{run_id}.json")
    output.write_text(json.dumps(record, ensure_ascii=False, indent=2), encoding="utf-8")
    if response.status_code == 201:
        print(f"Task pending. Inspect taskId in {output}; no CSV was created.")
        return
    if response.status_code != 200 or not isinstance(payload, dict):
        raise ValueError(f"Unexpected response; inspect {output}")
    export_results(payload, context, received_at, output.with_suffix(".csv"))


if __name__ == "__main__":
    main()

El tiempo de espera 120 es una configuración del cliente en este ejemplo, no una promesa de tiempo de respuesta del servicio. El tiempo de recepción es registrado por el cliente después de que llega la respuesta; no es una marca de tiempo suministrada por Google.

El escritor CSV de Python maneja delimitadores y campos entre comillas. Además, el ayudante también antepone marcadores de fórmula de hoja de cálculo comunes en el texto exportado. Preserve el JSON como el registro original, porque el CSV es una vista transformada destinada a la inspección. Revise la configuración de importación de texto antes de abrir valores de fuentes externas en una hoja de cálculo.

El ejemplo exporta solo q, gl y hl de su entrada. Si agrega una ubicación, un dominio o un desplazamiento de paginación, extienda las columnas CSV para retener esas dimensiones también. El JSON guardado ya contiene el objeto de entrada completo.

Interpretar la Respuesta Antes de Construir un Informe

Una respuesta HTTP 200 contiene los datos de la tarea, mientras que HTTP 201 indica procesamiento y proporciona un taskId. Una tarea pendiente no debe crear una observación de resultados vacíos. El script conserva su registro JSON y omite la exportación CSV en ese caso.

Para respuestas de datos exitosas, distinga un arreglo vacío de un campo organic_results ausente o inutilizable. Otros módulos pueden seguir presentes. El script preserva la respuesta y le pide que la inspeccione cuando no exista un arreglo utilizable.

Lea position como la posición suministrada para ese resultado devuelto. Antes de combinar páginas en un rango global, verifique cómo el endpoint numera posiciones para sus solicitudes. start controla el desplazamiento de resultados, y la información de paginación puede guiar solicitudes posteriores; ninguno establece que cada resultado de Google se pueda recuperar.

Poner Datos de Búsqueda Estructurada en Práctica

Los resultados de búsqueda estructurada proporcionan entradas para flujos de trabajo que su aplicación construye alrededor de la API. La unidad útil es un resultado más su contexto de solicitud y tiempo de observación.

• Instantáneas de SEO: guarde observaciones para una lista de palabras clave fija, luego compare contextos coincidentes a lo largo del tiempo. La programación, el almacenamiento y la detección de cambios pertenecen a su canalización.
• Investigación de marca y competidores: revise qué dominios y títulos de página aparecen para sus consultas seleccionadas. La muestra describe esas búsquedas, en lugar de todas las menciones en la web o el tráfico de un sitio.
• Descubrimiento de fuentes de IA: pase títulos candidatos, enlaces y fragmentos a un paso de selección de fuentes. Obtenga páginas completas por separado cuando se necesite evidencia y verifique que las afirmaciones generadas coincidan con sus fuentes.

Para un equipo de contenido, la primera salida podría ser una breve lista de lectura con la consulta y el mercado adjunto. Para un desarrollador, podría ser una exportación repetible utilizada por un informe existente. Ambos comienzan con un registro de datos que hace visible su alcance.

Use estos ejemplos para la información pública que se le permite recopilar y usar. Retenga los campos necesarios para la tarea, proteja las credenciales y revise las condiciones que se aplican a la reutilización posterior.

Conclusión

La API de Búsqueda de Google proporciona a una aplicación datos de búsqueda estructurada con los que trabajar. Una integración útil también preserva la entrada, verifica el estado de la tarea y separa el descubrimiento de fuentes del análisis posterior. Comience con una sola consulta e inspeccione el JSON guardado antes de expandir el flujo de trabajo.

El flujo de trabajo de solicitud de API de Búsqueda de Google actualizado proporciona los detalles de conexión para adaptar este ejemplo a su propio proyecto.

FAQ

P: ¿Es esta una API proporcionada por Google?

Este artículo describe la API de Búsqueda de Google de Scrapeless, un servicio de Scrapeless para recuperar datos de Búsqueda de Google. No alega una asociación oficial con Google.

P: ¿Necesita gestionar un navegador o un proxy?

La API administrada maneja la infraestructura de recopilación en el lado del servicio. Su cliente envía solicitudes HTTP y procesa los datos devueltos.

P: ¿Incluye la API datos históricos de clasificación?
El flujo de trabajo descrito aquí crea historia al guardar tus propias observaciones. No recupera un historial de clasificación preexistente.

P: ¿Puede la misma API buscar imágenes?

El producto admite búsquedas de imágenes de Google, con tbm=isch identificado en la referencia de parámetros. Inspecciona la respuesta de la imagen por separado; el mapeo CSV de este artículo es para resultados web orgánicos.

P: ¿Contiene un fragmento de búsqueda la página completa?

Un fragmento es un extracto asociado con un resultado de búsqueda. Un flujo de trabajo que necesita la evidencia completa de la página debe obtener y revisar el contenido de destino por separado.

P: ¿Qué debería suceder cuando la solicitud devuelve HTTP 201?

Conserva el taskId y trata la tarea como pendiente. Completa el flujo de trabajo del resultado de la tarea documentada antes de procesarlo como datos de búsqueda finalizados.