Scraper de Google Maps: extracción de clientes potenciales de código abierto a gran escala

Recopilar datos estructurados de negocios locales es útil para la prospección de ventas, la investigación de mercado, el SEO local, el enriquecimiento y la automatización, pero copiar manualmente fichas de Google Maps no es escalable. El proyecto de código abierto gosom/google-maps-scraper convierte las búsquedas de Google Maps en registros estructurados que contienen detalles del negocio, información de contacto, reseñas, coordenadas y direcciones de correo electrónico opcionales.

El proyecto cuenta con licencia MIT y ofrece varias formas de ejecutar el scraper: una interfaz de línea de comandos, una interfaz web local, una API REST, una edición SaaS opcional autoalojada y una habilidad para agentes de IA destinada a flujos de trabajo en lenguaje natural. Está escrito principalmente en Go y utiliza Playwright para la extracción basada en navegador.

Qué recopila el scraper

Un resultado típico puede incluir más de 33 campos, entre ellos:

Nombre, categoría, descripción y estado del negocio
Dirección y dirección completa con formato
Número de teléfono y sitio web oficial
Enlace de Google Maps, Place ID, CID y otros identificadores
Valoración media, número de reseñas, desglose de valoraciones y reseñas de clientes
Latitud, longitud, zona horaria, código plus y URL de Street View
Horarios de apertura e información sobre las horas de mayor afluencia
Rango de precios, reservas, menú y enlaces para pedidos en línea
Imágenes, miniatura, estado del propietario, tarjetas de crédito aceptadas y metadatos adicionales
Direcciones de correo electrónico descubiertas mediante el rastreo opcional de los sitios web de los negocios

La recopilación ampliada de reseñas puede obtener aproximadamente hasta 300 reseñas por lugar con la opción -extra-reviews. La extracción de correos electrónicos es opcional, ya que visitar el sitio web de cada negocio aumenta considerablemente el tiempo de ejecución.

Inicio rápido con Docker

Docker es el método de instalación recomendado porque la imagen incluye el entorno de automatización del navegador. Crea un directorio de salida y monta un archivo de entrada que contenga una consulta por línea:

mkdir -p gmaps-output

docker run \\
  -v gmaps-playwright-cache:/opt \\
  -v "$PWD/example-queries.txt:/queries.txt:ro" \\
  -v "$PWD/gmaps-output:/out" \\
  gosom/google-maps-scraper \\
  -input /queries.txt \\
  -results /out/results.csv \\
  -depth 1 \\
  -exit-on-inactivity 3m

Un archivo de consultas podría tener este aspecto:

restaurantes en Berlín
empresas de software en Austin
cafeterías en Atenas

La salida predeterminada es CSV. Para escribir JSON, añade -json y utiliza una ruta de resultados con extensión .json:

docker run \\
  -v gmaps-playwright-cache:/opt \\
  -v "$PWD/queries.txt:/queries.txt:ro" \\
  -v "$PWD/output:/out" \\
  gosom/google-maps-scraper \\
  -input /queries.txt \\
  -results /out/results.json \\
  -json \\
  -depth 1 \\
  -exit-on-inactivity 3m

La primera ejecución puede descargar bibliotecas del navegador e inicializar la caché de Playwright. Persistir /opt en un volumen de Docker con nombre evita repetir ese trabajo.

Tres formas de utilizarlo

1. Línea de comandos

La CLI es ideal para trabajos repetibles, scripts de shell, tareas de cron y canalizaciones de datos. Entre las opciones importantes se incluyen:

Opción	Propósito
`-input`	Archivo de entrada que contiene consultas o URL de Google Maps
`-results`	Ruta de salida CSV, JSON o JSONL
`-depth`	Profundidad máxima de desplazamiento de resultados; el valor predeterminado es 10
`-c`	Número de trabajos de scraping simultáneos; el valor predeterminado es la mitad de los núcleos de CPU
`-email`	Rastrea los sitios web de los negocios para obtener direcciones de correo electrónico
`-extra-reviews`	Recopila datos ampliados de reseñas
`-resume`	Continúa un scraping interrumpido basado en archivos
`-fast-mode`	Recopila rápidamente hasta 21 resultados por consulta
`-lang`	Idioma de Google Maps, como `de`
`-geo`	Coordenadas de búsqueda, por ejemplo `37.7749,-122.4194`
`-radius`	Radio de búsqueda en metros
`-grid-bbox`	Divide un cuadro delimitador geográfico en celdas

2. Interfaz web y API REST

Inicia la interfaz web local con:

mkdir -p gmapsdata

docker run \\
  -v "$PWD/gmapsdata:/gmapsdata" \\
  -p 8080:8080 \\
  gosom/google-maps-scraper \\
  -data-folder /gmapsdata

Abre http://localhost:8080. El servidor también expone una especificación OpenAPI 3.0.3 en http://localhost:8080/api/docs.

Los principales endpoints de la API son:

POST /api/v1/jobs — crea un trabajo de scraping
GET /api/v1/jobs — lista los trabajos
GET /api/v1/jobs/{id} — consulta un trabajo
DELETE /api/v1/jobs/{id} — elimina un trabajo
GET /api/v1/jobs/{id}/download — descarga los resultados en CSV

Esto hace que el scraper sea adecuado para integrarlo con paneles internos, flujos de trabajo de CRM o servicios programados de generación de clientes potenciales.

3. Flujo de trabajo con agentes de IA

El repositorio incluye un paquete Agent Skills compatible con herramientas como Claude Code, Codex, Cursor y GitHub Copilot. Instálalo con:

npx skills add gosom/google-maps-scraper

A continuación, puedes solicitar algo como:

Busca dentistas en Berlín e incluye sus sitios web y direcciones de correo electrónico.

La habilidad puede inferir los valores predeterminados de búsqueda, realizar una pequeña ejecución de validación, iniciar el rastreo de Docker, supervisar el progreso y ayudar a guardar o analizar los resultados. Las credenciales del proxy se introducen mediante un aviso local enmascarado de la terminal, en lugar de pegarlas en la conversación con el agente. Se requieren Docker y Node.js en macOS, Linux o Windows mediante WSL.

Gestión de trabajos grandes

El proyecto informa de aproximadamente 120 lugares por minuto con -c 8 -depth 1, aunque el rendimiento real depende de la complejidad de las consultas, los recursos del navegador, las condiciones de red y los bloqueos.

Una estimación representativa es:

Palabras clave	Resultados por palabra clave	Lugares totales	Tiempo estimado
100	16	1.600	~13 minutos
1.000	16	16.000	~2,5 horas
10.000	16	160.000	~22 horas

La concurrencia controla el número de trabajos simultáneos. La configuración de los procesos del navegador y de las páginas ofrece un control adicional:

./google-maps-scraper \\
  -c 8 \\
  -browser-pool-size 2 \\
  -pages-per-browser 4 \\
  -input queries.txt \\
  -results results.csv \\
  -depth 1

Aquí, ocho trabajos se distribuyen entre dos procesos del navegador, con cuatro pestañas por navegador. Supervisa el uso de recursos con htop o docker stats; Chromium puede consumir una cantidad considerable de CPU y memoria. El producto de browser-pool-size y pages-per-browser debería coincidir aproximadamente con -c o superarlo para mantener ocupados a los trabajadores.

Para trabajos interrumpidos, utiliza el modo de reanudación:

./google-maps-scraper \\
  -resume \\
  -input queries.txt \\
  -results results.csv \\
  -depth 10

El modo de reanudación lee la salida CSV o JSONL existente, omite los lugares ya escritos y mantiene un archivo auxiliar <results>.resume.json que contiene las consultas de entrada completadas. Requiere una salida en un archivo normal y es incompatible con stdout, escritores personalizados, la salida de LeadsDB y el modo rápido.

Cobertura geográfica con scraping en cuadrícula

Una sola búsqueda de Google Maps puede no mostrar suficientes resultados para una zona densa. El scraping en cuadrícula divide un cuadro delimitador en celdas y ejecuta una consulta desde cada celda:

./google-maps-scraper \\
  -input queries.txt \\
  -results peristeri-cafes.csv \\
  -grid-bbox "38.0077,23.6719,38.0257,23.6947" \\
  -grid-cell 0.5 \\
  -zoom 16 \\
  -depth 1 \\
  -c 4

El modo de cuadrícula ayuda a aumentar la cobertura geográfica, pero no limita estrictamente los resultados al cuadro delimitador. Para aplicar un filtrado estricto por distancia, utiliza -geo con -radius en el modo rápido o filtra posteriormente los registros mediante la latitud y la longitud.

El modo rápido devuelve hasta 21 resultados por consulta, ordenados por distancia:

./google-maps-scraper \\
  -input queries.txt \\
  -results results.csv \\
  -fast-mode \\
  -zoom 15 \\
  -radius 5000 \\
  -geo '37.7749,-122.4194'

El modo rápido se encuentra actualmente en fase beta y puede ser más susceptible a bloqueos. No se puede combinar con -grid-bbox.

Configuración del proxy

Para trabajos grandes, los proxies pueden ayudar a distribuir el tráfico y reducir la limitación de velocidad. Se admiten los protocolos SOCKS5, SOCKS5H, HTTP y HTTPS:

./google-maps-scraper \\
  -input queries.txt \\
  -results results.csv \\
  -proxies 'socks5://user:pass@host:port,http://host2:port2' \\
  -depth 1 \\
  -c 2

También puedes colocar una URL de proxy por línea en un archivo:

./google-maps-scraper \\
  -input queries.txt \\
  -results results.csv \\
  -proxies-file proxies.txt

El uso de proxies no sustituye un diseño responsable del rastreo. Comienza con una concurrencia baja, valida una muestra pequeña y cumple las leyes aplicables y las condiciones que rigen los datos a los que accedes.

Exportación directa a LeadsDB

En lugar de escribir archivos intermedios, el scraper puede enviar los registros directamente a LeadsDB, que ofrece deduplicación, filtrado, acceso mediante API y exportaciones:

export LEADSDB_API_KEY="your-api-key"
./google-maps-scraper \\
  -input queries.txt \\
  -exit-on-inactivity 3m

También puedes proporcionar la clave explícitamente con -leadsdb-api-key. Los campos de Google Maps se asignan a campos de clientes potenciales como nombre, categoría, teléfono, sitio web, dirección, coordenadas, valoración, número de reseñas, correo electrónico, URL del logotipo e ID de origen. Los metadatos adicionales de Maps se conservan como atributos personalizados.

Escalado con PostgreSQL y Kubernetes

Para cargas de trabajo distribuidas, PostgreSQL puede actuar como proveedor de trabajos compartido. Inicia la base de datos de desarrollo, carga los trabajos y ejecuta trabajadores del scraper en varias máquinas:

docker-compose -f docker-compose.dev.yaml up -d

./google-maps-scraper \\
  -dsn "postgres://postgres:postgres@localhost:5432/postgres" \\
  -produce \\
  -input example-queries.txt \\
  -lang en

./google-maps-scraper \\
  -c 2 \\
  -depth 1 \\
  -dsn "postgres://postgres:postgres@localhost:5432/postgres"

Una implementación de Kubernetes puede ejecutar varias réplicas:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: google-maps-scraper
spec:
  replicas: 3
  selector:
    matchLabels:
      app: google-maps-scraper
  template:
    metadata:
      labels:
        app: google-maps-scraper
    spec:
      containers:
        - name: google-maps-scraper
          image: gosom/google-maps-scraper:latest
          args: ["-c", "1", "-depth", "10", "-dsn", "postgres://user:pass@host:5432/db"]
          resources:
            requests:
              memory: "512Mi"
              cpu: "500m"

Los navegadores sin interfaz requieren asignaciones significativas de CPU y memoria, por lo que las solicitudes de recursos deben ajustarse mediante pruebas de carga en lugar de copiarse sin más.

Compilación desde el código fuente

El proyecto requiere Go 1.26.6 o posterior:

git clone https://github.com/gosom/google-maps-scraper.git
cd google-maps-scraper
go mod download
go build
./google-maps-scraper \\
  -input example-queries.txt \\
  -results results.csv \\
  -exit-on-inactivity 3m

Los desarrolladores también pueden crear plugins de escritor personalizados en Go:

go build -buildmode=plugin -tags=plugin -o myplugin.so myplugin.go
./google-maps-scraper \\
  -writer ~/plugins:MyWriter \\
  -input queries.txt

Consideraciones operativas

La telemetría anónima está activada de forma predeterminada y se puede desactivar con:

export DISABLE_TELEMETRY=1

El repositorio cuenta con licencia MIT, pero los usuarios siguen siendo responsables de cumplir las normas aplicables sobre privacidad, protección de datos y condiciones de los sitios web. Evita recopilar datos que no necesites, protege la información de contacto exportada e incorpora límites de velocidad y políticas de reintento en los flujos de trabajo de producción.

Con su combinación de extracción basada en navegador, salida estructurada, trabajos reanudables, controles geográficos, compatibilidad con proxies, APIs y ejecución distribuida, Google Maps Scraper es más que un comando puntual. Es una base práctica para desarrolladores que necesitan convertir resultados de búsquedas locales en canalizaciones de datos repetibles y auditables.

Fuente

gosom/google-maps-scraper: scrape data from Google Maps. Extracts data such as the name, address, phone number, website URL, rating, reviews number, latitude and longitude, reviews,email and more for each place