API de Scraper de Imágenes de Google: Lee la vertical de imágenes como JSON

Puntos Clave:

• Una solicitud POST, sin navegador. Los datos de Google Images provienen de una sola POST al actor scraper.google.search con tbm: "isch". La API del Scraper renderiza la página y la analiza del lado del servidor; recibes un JSON de vuelta.
• El vertical de imágenes es un campo de entrada. tbm: "isch" cambia el actor de búsqueda de Google al vertical de Imágenes; q contiene tu consulta. Todo lo demás es opcional.
• Un encabezado de autenticación en todas partes. Cada llamada lleva x-api-token: <tu clave>. Una clave de cuenta cubre el actor y cada otro actor de scraper.*.
• JSON analizado, aplanado en el nivel superior. El actor devuelve metadata, search_information y suggested_searches directamente — sin un envoltorio de result que desempaquetar. Cada chip de refinamiento en suggested_searches lleva una miniatura en línea data:image/jpeg;base64.
• La cuadrícula completa de imágenes está en metadata.rawUrl. El objeto analizado muestra los chips de refinamiento y los metadatos de búsqueda; metadata.rawUrl apunta a la página de Google Images completamente renderizada almacenada cuando necesitas cada URL de imagen que el objeto analizado no aplana.
• Gratis para comenzar. Las nuevas cuentas de Scrapeless incluyen créditos gratuitos para la API de Scraper — regístrate en app.scrapeless.com.

Introducción: leer el vertical de Imágenes como JSON

Google Images se basa en uno de los índices visuales más grandes de la web abierta, y mucho trabajo depende de lo que ofrece: investigación visual de productos, monitoreo de marcas y logotipos, creación de conjuntos de datos de imágenes para entrenamiento de modelos, seguimiento de cómo una consulta se representa en diferentes regiones y obtención de referencias de diseño a gran escala. La consulta es la entrada; una cuadrícula de imágenes y una fila de chips de refinamiento son la salida.

Obtener esa salida de manera programática es la parte difícil. La página de Imágenes se renderiza con JavaScript, las miniaturas están incrustadas como base64 dentro de la carga del script, los chips de refinamiento y las URL de imágenes están enterrados en los datos de hidratación de la página, y una solicitud anónima recibe un desafío en lugar de una cuadrícula. Un scraper manual tiene que renderizar la página, superar la capa anti-bot y realizar ingeniería inversa al marcado — tres trabajos, todos los cuales cambian cuando Google lanza un rediseño.

Esta guía explica el actor scraper.google.search en la API de Scraper de Scrapeless, ejecutado con tbm: "isch". Una solicitud HTTP devuelve un objeto analizado más una copia almacenada de la página de imágenes renderizada. Sin navegador que controlar, sin analizador que mantener. El ejemplo trabajado a continuación es la captura real de q: "golden retriever"; una guía complementaria de la API de Scraper cubre la familia de respuestas de AI con la misma forma de solicitud.

Por qué la API de Scraper para Google Images

• Sin navegador, sin analizador que mantener. El actor renderiza y analiza la página de Imágenes en el servidor; recibes campos estructurados, no un DOM que caminar o un blob de base64 que decodificar a mano.
• Una entrada cambia el vertical. El mismo actor de búsqueda de Google sirve resultados web e imágenes — establece tbm: "isch" y la respuesta regresa como el vertical de Imágenes.
• Egreso residencial y renderización están integrados. El geo-enrutamiento y el renderizado de JavaScript se ejecutan dentro del actor; envías { actor, input } y lees el resultado.
• Una forma para leer. El objeto analizado de Imágenes está aplanado en el nivel superior, por lo que un envoltorio de cliente escrito una vez maneja la respuesta sin desempaquetar sobres anidados.

Obtén tu clave de API en el plan gratuito en app.scrapeless.com. El actor de búsqueda de Google es parte de Deep SerpApi, que está en el catálogo de precios.

Requisitos Previos

• Una cuenta de Scrapeless y clave de API — regístrate en app.scrapeless.com.
• curl para la prueba rápida, o Python 3.10+ para el cliente a continuación.
• Familiaridad básica con HTTP y JSON.

Almacena tu clave en el entorno para que nunca aparezca en el código:

export SCRAPELESS_API_KEY=tu_token_api_aqui

La solicitud

Google Images utiliza el endpoint de site/SERP. Nombras el actor, le entregas una entrada y envías tu clave en el encabezado.

• Endpoint: POST https://api.scrapeless.com/api/v1/scraper/request
• Actor: scraper.google.search
• Encabezado de Autenticación: x-api-token: $SCRAPELESS_API_KEY

El cuerpo es { "actor": "<nombre>", "input": { … } }. Para el vertical de Imágenes, la entrada son dos campos:

{
  "actor": "scraper.google.search",
  "input": { "q": "golden retriever", "tbm": "isch" }
}

Ejemplo — curl y Python

La verificación más rápida es una sola llamada curl:

curl -sS -X POST https://api.scrapeless.com/api/v1/scraper/request \
  -H "Content-Type: application/json" \
  -H "x-api-token: ${SCRAPELESS_API_KEY}" \
  -d '{
    "actor": "scraper.google.search",
    "input": { "q": "retriever dorado", "tbm": "isch" }
  }'

La misma solicitud en Python, con la respuesta analizada directamente en un diccionario:

import os
import json
import requests

ENDPOINT = "https://api.scrapeless.com/api/v1/scraper/request"


def scrape_google_images(query: str) -> dict:
    resp = requests.post(
        ENDPOINT,
        headers={
            "Content-Type": "application/json",
            "x-api-token": os.environ["SCRAPELESS_API_KEY"],
        },
        json={"actor": "scraper.google.search", "input": {"q": query, "tbm": "isch"}},
        timeout=120,
    )
    resp.raise_for_status()
    return resp.json()


if __name__ == "__main__":
    data = scrape_google_images("retriever dorado")
    # google.search aplana el resultado analizado en el nivel superior,
    # así que data.get("result", data) vuelve a la respuesta completa.
    print(json.dumps(data.get("result", data), indent=2, ensure_ascii=False))

Debido a que el actor de búsqueda de Google aplana su salida analizada en el nivel superior, no hay una clave result a la que acceder — data.get("result", data) simplemente devuelve toda la respuesta, y puedes leer search_information y suggested_searches directamente de ella.

Obtén tu clave API en el plan gratuito: app.scrapeless.com

Lo que obtienes de vuelta

Para la vertical de Imágenes, el actor proporciona un sobre metadata de Scrapeless, la search_information que Google devuelve, y la fila de chips de refinamiento de imágenes (suggested_searches) que Google presenta sobre la cuadrícula. Cada chip lleva su propia miniatura en línea. Esta es la captura real para q: "retriever dorado", tbm: "isch":

// Captura real para q:"retriever dorado", tbm:"isch".
// miniaturas en base64 recortadas; suggested_searches abreviado a 2 de 5 chips — muestra ilustrativa.
{
  "metadata": {
    "engine": "google.search",
    "rawUrl": "https://api.scrapeless.com/storage/scrapeless.scraper.google.search/…_1781025000.html"
  },
  "pagination": {},
  "search_information": {
    "organic_results_state": "Resultados para la ortografía exacta",
    "query_displayed": "retriever dorado",
    "total_results": 0,
    "time_taken_displayed": ""
  },
  "suggested_searches": [
    {
      "name": "Cachorro",
      "link": "https://www.google.com/search?sca_esv=…&gl=us&q=retriever+dorada+cachorro&uds=…&udm=2&sa=X&…",
      "uds": "",
      "q": "Cachorro retriever dorado",
      "thumbnail": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/…"
    },
    {
      "name": "Bonito",
      "link": "https://www.google.com/search?sca_esv=…&gl=us&q=bonito+retriever+dorada&uds=…&udm=2&sa=X&…",
      "uds": "",
      "q": "Bonito retriever dorado",
      "thumbnail": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/…"
    }
  ]
}

Campo por campo:

Algunas observaciones honestas sobre la forma:

• El objeto analizado revela los chips de refinamiento, no un array plano images_results. Para el vertical isch, el actor devuelve suggested_searches más la página renderizada en metadata.rawUrl. Cuando necesites cada URL de imagen en la cuadrícula, obtén metadata.rawUrl: esa página almacenada contiene el conjunto completo que el objeto analizado no aplana.
• Las miniaturas son inline base64. El thumbnail de cada chip es un valor completo data:image/jpeg;base64, utilizable sin una segunda solicitud; el fixture las recorta para mejorar la legibilidad.
• search_information refleja lo que muestra Google. total_results y time_taken_displayed pueden regresar como 0 y vacíos en el vertical de imágenes, donde Google no muestra la línea "Acerca de N resultados" que ofrece en la búsqueda web.
• Trata los campos por chip como anulables. uds está presente en cada chip pero vacío en esta captura, y el conteo de chips varía según la consulta: lee lo que hay en vez de asumir una longitud fija.

Conclusión

Leer Google Imágenes se reduce a una decisión y una solicitud: apunta al actor scraper.google.search en el vertical de Imágenes con tbm: "isch", envía { actor, input } con tu x-api-token, y lee los campos analizados. La respuesta se aplana en el nivel superior: metadata, search_information, y los chips de refinamiento suggested_searches con sus miniaturas inline, mientras que metadata.rawUrl contiene la página completamente renderizada para la cuadrícula completa. Escribe el envoltorio del cliente una vez, dirígelo a la consulta que necesites, y la misma forma cubre los actores de respuesta AI cuando la canalización crezca.

¿Listo para construir tu canalización de datos de imágenes impulsada por IA?

Únete a nuestra comunidad para reclamar un plan gratuito y conectarte con desarrolladores que están construyendo canalizaciones de Google Imágenes: Discord · Telegram.

Regístrate en app.scrapeless.com para créditos gratuitos de Scraper API y apunta al actor scraper.google.search a las consultas, idiomas y regiones que tu canalización de imágenes necesita.

Preguntas Frecuentes

Q: ¿Es legal rastrear Google Imágenes?

El actor recopila datos públicamente visibles. Las reglas varían según la jurisdicción y los términos de servicio de Google, así que revisa los ToS relevantes y consulta con un abogado para tu caso de uso antes de ejecutar a gran escala. Nunca recojas datos personales protegidos bajo GDPR o CCPA, y respeta los derechos asociados con imágenes individuales.

Q: ¿Cómo me autentico?

Cada solicitud lleva el encabezado x-api-token: <tu clave>. Una clave de cuenta funciona en scraper.google.search y en todos los demás actores. Crea una clave en el plan gratuito en app.scrapeless.com.

Q: ¿Cómo cambio de resultados web a imágenes?

Establece tbm: "isch" en la entrada. El mismo actor scraper.google.search sirve el SERP web por defecto; tbm: "isch" selecciona el vertical de Imágenes y cambia la forma analizada a los chips de refinamiento de imágenes más la página de imagen renderizada.

Q: ¿Dónde están las URLs de imagen reales?

El objeto analizado revela los chips de refinamiento (suggested_searches) y los metadatos de búsqueda. La cuadrícula completa de URLs de imágenes se encuentra en la página almacenada en metadata.rawUrl: obtén esa URL cuando necesites cada imagen en la página de resultados, no solo la fila de refinamiento.

Q: ¿Puedo restringir resultados por idioma o país?

Sí. Las entradas opcionales hl (idioma de la interfaz), gl (país / localidad) y google_domain limitan la solicitud; por ejemplo, { "q": "golden retriever", "tbm": "isch", "hl": "es", "gl": "es" }.

Q: ¿Necesito un proxy?

No. La salida residencial y la geo-enrutación están integradas en el actor: tú envías la entrada y el actor maneja la red y la capa de renderizado.

Q: ¿Puedo ejecutar esto sin un SDK o agente de IA?

Sí. Es HTTP simple: curl, requests de Python, fetch de Node, o cualquier lenguaje con un cliente HTTP funciona directamente contra POST /api/v1/scraper/request. No se requiere SDK.