Cómo Extraer Google Imágenes en JSON con URLs a Resolución Completa

Google Imágenes parece una simple cuadrícula de fotos, pero es una de las páginas más difíciles de extraer de la web. Lo que ves no es lo que está en el HTML. Las miniaturas se cargan de forma diferida, los originales a resolución completa están ocultos tras un clic y una segunda petición, y las URLs que sí aparecen en el marcado suelen ser cadenas base64 o redirecciones efímeras en lugar de la imagen real en el sitio del editor. Si escribes un scraper ingenuo, terminas con una carpeta de vistas previas de 200 píxeles y sin saber de dónde salió ninguna.

El nuevo plugin de Google Imágenes elimina todo ese problema. Envías una palabra clave y recibes un array JSON donde cada resultado ya trae la URL de la imagen original a resolución completa, la página en la que aparece y el dominio de origen. Este artículo explica por qué Google Imágenes es complicado, qué devuelve el plugin y cómo construir un conjunto de datos de imágenes real con él.

Por Qué Google Imágenes Es Difícil de Extraer

Antes del plugin, todos los enfoques habituales tenían una trampa:

• Las miniaturas visibles están reducidas. El src que puedes leer directamente de la cuadrícula apunta a una miniatura alojada por Google, normalmente de unos pocos cientos de píxeles. Sirve para una vista previa, pero no si necesitas el recurso real.
• Las URLs originales están diferidas. La imagen a resolución completa vive en el propio servidor del editor, y Google solo revela esa URL tras una interacción. Está escondida dentro de una carga de JavaScript, no en el HTML inicial, así que una petición HTTP simple nunca la ve.
• El marcado es ruidoso a propósito. Los nombres de clase están ofuscados y cambian a menudo, los datos en línea están codificados y gran parte de la página se construye en el cliente. Los selectores que funcionan hoy se rompen la semana que viene.
• Es una superficie de Google sensible a los bots. Si martilleas la página de resultados desde una sola IP sin huella de navegador, obtienes un desafío o una página vacía en lugar de resultados.

Puedes resolver todo eso tú mismo con un navegador headless, esperas cuidadosas y análisis de la carga útil, pero es mucho código frágil que mantener para lo que debería ser una simple consulta.

Qué Devuelve el Plugin de Google Imágenes

El plugin toma una frase de búsqueda -lo mismo que escribirías en Google Imágenes- y devuelve los resultados de imágenes como un array JSON estructurado. El detalle clave es que imageUrl es la imagen real, a resolución completa, en el sitio de origen, no una miniatura de Google.

Para cada resultado obtienes campos como:

• position - posición en los resultados
• title - el texto alt/título de la imagen
• imageUrl - la URL de la imagen original a resolución completa en el sitio del editor
• sourceUrl - la página donde aparece la imagen
• sourceDomain - el host de esa página, como example.com
• siteName - el nombre legible del sitio cuando está disponible
• thumbnailUrl - la vista previa alojada por Google, si quieres una versión ligera
• width y height - las dimensiones de la imagen original en píxeles

Como la URL original y la página de origen llegan juntas, siempre sabes qué es la imagen y dónde reside legítimamente, algo que importa mucho para las licencias y la atribución.

La Petición

El endpoint es una sola llamada POST. El único parámetro obligatorio es q, la frase de búsqueda. Unos pocos parámetros opcionales controlan ubicación, idioma y número de resultados:

• q (obligatorio) - la frase de búsqueda, por ejemplo panda rojo
• proxy_country - el país de la IP de salida como código ISO-2 (US, GB, DE)
• gl - el país de búsqueda de Google, ISO-2 en minúsculas (us, de, fr)
• max_results - cuántas imágenes devolver, de 1 a 100

Aquí tienes la llamada más simple posible con curl:

curl -X POST "https://api.scrapeunblocker.com/images/google-search?q=panda%20rojo&max_results=20" \
  -H "x-scrapeunblocker-key: YOUR_API_KEY"

Eso devuelve los primeros resultados de imágenes para la palabra clave, cada uno con su URL a resolución completa, en una sola respuesta. No gestionas un navegador, ni esperas la carga diferida, ni analizas ningún HTML.

La Respuesta

La respuesta es un único objeto JSON. El nivel superior repite la consulta y cuántos resultados llegaron, y el array results contiene las imágenes:

{
  "q": "panda rojo",
  "proxyCountry": "US",
  "resultsCollected": 20,
  "results": [
    {
      "position": 1,
      "title": "Panda rojo descansando en una rama",
      "imageUrl": "https://example.com/photos/red-panda-full.jpg",
      "sourceUrl": "https://example.com/wildlife/red-panda",
      "sourceDomain": "example.com",
      "siteName": "Example Wildlife",
      "thumbnailUrl": "https://encrypted-tbn0.gstatic.com/images?q=...",
      "width": 2400,
      "height": 1600
    }
  ]
}

Como la forma es estable, puedes mapearla directamente a una base de datos, una hoja de cálculo o una cola de descargas sin limpieza de HTML.

Llamarlo Desde Python

No necesitas el SDK para usar el plugin: cualquier cliente HTTP sirve. Aquí tienes un pequeño ejemplo con requests que ejecuta una búsqueda e imprime cada resultado:

import requests

API_KEY = "YOUR_API_KEY"
URL = "https://api.scrapeunblocker.com/images/google-search"

params = {
    "q": "panda rojo",
    "proxy_country": "US",
    "gl": "us",
    "max_results": 20,
}

resp = requests.post(URL, params=params, headers={"x-scrapeunblocker-key": API_KEY})
resp.raise_for_status()
data = resp.json()

for img in data["results"]:
    print(f"{img['position']:>2}. {img['width']}x{img['height']} "
          f"{img['sourceDomain']:<20} {img['imageUrl']}")

Si prefieres las herramientas oficiales, ScrapeUnblocker ofrece SDKs para Python, Node.js, Ruby y PHP, y el plugin también está disponible a través del panel y la referencia de la API. El paquete de Python se instala con pip install scrapeunblocker y lee tu clave desde una variable de entorno, así que puedes ahorrarte pasar la cabecera a mano.

Descargar las Imágenes Reales

El sentido de obtener la URL a resolución completa es que puedes descargar el archivo real. Aquí tienes un bucle de búsqueda y descarga que guarda cada imagen original en disco, nombrada por dominio de origen:

import os
import requests
from urllib.parse import urlparse

API_KEY = "YOUR_API_KEY"
SEARCH_URL = "https://api.scrapeunblocker.com/images/google-search"

os.makedirs("images", exist_ok=True)

params = {"q": "maquina de escribir antigua", "max_results": 30}
data = requests.post(SEARCH_URL, params=params,
                     headers={"x-scrapeunblocker-key": API_KEY}).json()

for img in data["results"]:
    url = img["imageUrl"]
    ext = os.path.splitext(urlparse(url).path)[1] or ".jpg"
    name = f"images/{img['position']:02d}_{img['sourceDomain']}{ext}"
    try:
        r = requests.get(url, timeout=20)
        r.raise_for_status()
        with open(name, "wb") as f:
            f.write(r.content)
        print("guardado", name)
    except requests.RequestException as e:
        print("omitido", url, e)

Como imageUrl apunta al servidor de origen y no a una miniatura de Google, algunos hosts pueden limitar la tasa o proteger contra el hotlinking. Envuelve la descarga en un try/except, añade una breve pausa entre peticiones y omite las que fallen en lugar de dejar que un mal host detenga toda la ejecución.

Qué Puedes Construir Con Ello

Los resultados de búsqueda de imágenes como JSON limpio abren varios casos de uso prácticos:

• Conjuntos de datos de entrenamiento y referencia. Reúne imágenes etiquetadas para una categoría, manteniendo title, sourceUrl y sourceDomain junto a cada archivo para poder rastrear la procedencia y filtrar por licencia más tarde.
• Monitorización de marca y logotipos. Busca tu marca o producto y ve qué sitios usan tus imágenes, y a qué resolución.
• Investigación de contenido y SEO. Comprueba qué imágenes posicionan para una palabra clave, qué tamaño tienen y qué dominios dominan los resultados de un tema.
• Enriquecimiento de productos y catálogos. Obtén imágenes candidatas para productos por nombre y elige el resultado de mayor resolución para cada uno.

Como cada resultado incluye width y height, puedes filtrar imágenes por encima de un tamaño mínimo en una línea antes de descargar nada.

Consejos Prácticos

Algunas cosas que conviene tener en cuenta:

• Sé específico con las palabras clave. Los términos amplios devuelven imágenes de stock genéricas; una frase precisa devuelve un conjunto más ajustado y relevante. Trata q exactamente como tratarías una búsqueda real en Google Imágenes.
• Fija la ubicación cuando importe. Los resultados de imágenes pueden variar por región. Usa proxy_country y gl juntos cuando necesites resultados reproducibles y precisos por región.
• Filtra por dimensiones pronto. Usa width y height para descartar imágenes diminutas antes de gastar ancho de banda descargándolas.
• Respeta las licencias. Una URL de imagen pública no es lo mismo que una licencia para usarla. Guarda sourceUrl y siteName con cada imagen y verifica los derechos de uso antes de publicar o redistribuir nada.
• Gestiona los fallos de descarga con elegancia. Los originales viven en servidores de terceros, así que espera algunos 403 y timeouts y sáltalos.

Preguntas Frecuentes

¿Obtengo la imagen real o solo una miniatura? Obtienes la real. imageUrl es el original a resolución completa alojado en el sitio de origen. También se incluye un thumbnailUrl por si quieres una vista previa ligera.

¿Cuántas imágenes puede devolver una llamada? Hasta 100, controlado por max_results. Ajústalo al número que realmente necesites para mantener las respuestas pequeñas y rápidas.

¿Puedo apuntar a un país o idioma concreto? Sí. Usa proxy_country para la IP de salida y gl para el país de búsqueda de Google. Fija ambos cuando te importe de qué región proceden los resultados.

¿Es legal extraer Google Imágenes? Leer resultados de búsqueda públicos suele estar bien, pero las imágenes en sí son obras con derechos de autor de sus editores. Obtener una URL no es una licencia. Comprueba y respeta siempre los derechos de uso de cada imagen antes de reutilizarla.

¿Y si necesito imágenes de un sitio concreto? Añade un término estilo site: a tu consulta, o extrae directamente las páginas de ese sitio con el endpoint de scraping estándar y saca las imágenes que necesites del marcado.

Para Terminar

Google Imágenes convierte una cuadrícula de aspecto sencillo en un dolor de cabeza de scraping: miniaturas reducidas, URLs originales diferidas, marcado ofuscado y una superficie sensible a los bots. El plugin de Google Imágenes reduce todo eso a una sola llamada que devuelve URLs de imágenes a resolución completa, páginas de origen y dimensiones como JSON limpio, para que dediques tu tiempo a construir el conjunto de datos en lugar de a hacer ingeniería inversa de la página.

Si quieres probarlo, el plugin está disponible en el panel de ScrapeUnblocker y documentado junto a los demás plugins en la documentación para desarrolladores. Apúntalo a una palabra clave y mira cómo se ve la búsqueda de imágenes en forma de datos estructurados.