Google Maps Scraper Kit: scraper de Google Maps gratis para conseguir clientes con Claude Code

Google Maps Scraper Kit es un scraper de Google Maps gratis y open source que convierte una búsqueda como "dentistas en Quito" en un CSV con nombre, teléfono, correo, web, categoría, dirección, valoración y número de reseñas de cada negocio. Corre en tu propio equipo con Docker, no necesita clave de la API de Google ni créditos de un SaaS, y trae una skill para que Claude Code, Codex o Cursor lo manejen en lenguaje natural.

En este artículo leemos el código de la versión v1.1.0 y su motor, lo probamos de verdad con dos búsquedas en Quito, y te contamos para qué le sirve a una pyme y a una empresa grande de cualquier rubro, cómo instalarlo y, con el mismo cuidado, qué dicen los términos de Google y las leyes de datos de Ecuador, Europa y EE. UU. sobre usarlo.

Qué es Google Maps Scraper Kit y quién lo hace

• Repositorio: github.com/Mahanaicoach/google-maps-scraper-kit
• Versión analizada: v1.1.0 (último commit del 14 de octubre de 2026).
• Licencia: MIT, copyright de Mahan (@Mahanaicoach). Comprobada en el archivo LICENSE, no solo en la insignia del README.
• Motor: gosom/google-maps-scraper de Georgios Komninos, también MIT, en su imagen oficial de Docker v1.18.1 sin modificar.

El kit no reinventa el scraping. El motor de gosom ya hacía el trabajo duro: abre Google Maps en un navegador headless, recorre los resultados y guarda unos 34 campos por negocio. Lo que añade el kit es la capa que lo vuelve útil para ventas:

• Un docker-compose.yml que levanta el motor en 127.0.0.1:8080, solo en tu equipo.
• scripts/scrape.py, una CLI en Python sin dependencias que crea el trabajo, espera a que termine, descarga el CSV y deja solo los 8 campos de contacto.
• Geocodificación de la ciudad con OpenStreetMap, búsquedas por lotes, cuadrícula para pasar del tope de unos 120 resultados por búsqueda, y extracción de correos y redes sociales desde la web de cada negocio.
• Una skill y cuatro comandos (/scrape, /scrape-batch, /scrape-setup, /scrape-jobs) para Claude Code, con avisos de uso responsable incluidos.

Cómo funciona por dentro

Un scrape es un trabajo asíncrono contra la API REST local:

1. POST /api/v1/jobs con las palabras clave, la latitud y longitud como texto, la profundidad (depth) y el tiempo máximo en segundos (max_time). Sin lat, lon o max_time la API responde 422.
2. GET /api/v1/jobs/{id} hasta que el campo Status pasa de working a ok.
3. GET /api/v1/jobs/{id}/download devuelve el CSV con las 34 columnas, y el script se queda con title, phone, emails, website, category, address, review_rating y review_count.

Los correos salen de dos pasadas. El motor visita la web de cada negocio con email: true, y después el script revisa hasta tres páginas de contacto o "acerca de" de las filas que siguen vacías. Las redes (--socials) se sacan con expresiones regulares sobre el HTML de la portada: cero tokens de IA aunque lo maneje Claude.

Beneficios para pequeñas y grandes empresas

La pregunta útil no es "cuántos contactos saca", sino qué decisión de negocio te ahorra o te mejora. Separamos los usos por tamaño porque cambian bastante.

Para pymes y emprendedores

• Lista de prospectos local en minutos y sin coste. Una distribuidora de insumos dentales, una agencia web o un proveedor de software para restaurantes obtiene en una tarde la lista de clínicas, consultorios o locales de su ciudad con teléfono y web. Las alternativas en la nube cobran por resultado o por suscripción.
• Encontrar a quien le falta algo que vendes. Filtra las filas sin website y tienes negocios que aún no tienen página web; filtra por review_count bajo y tienes negocios a los que les vendría bien gestionar reseñas.
• Estudiar a la competencia antes de abrir. Cuántas cafeterías, ferreterías o gimnasios hay por barrio, qué valoración media tienen y cuántas reseñas acumulan. Es un estudio de mercado básico que antes se hacía a pie.
• Encontrar proveedores y aliados. Talleres, imprentas, transportistas o contadores de una zona, con su valoración para empezar por los mejores.
• Revisar tu propia ficha. Comprueba cómo apareces tú frente a los demás de tu categoría: categoría, reseñas y si tu web está enlazada.

Para medianas y grandes empresas

• Planificación de territorios comerciales. Con --grid y búsquedas por lotes, un equipo de ventas reparte zonas según la densidad real de clientes potenciales por ciudad, en lugar de por intuición.
• Expansión y elección de ubicaciones. Una cadena de farmacias, un banco o una franquicia de comida ve dónde se concentran competidores y negocios complementarios antes de abrir sucursal.
• Enriquecer y depurar el CRM. Cruzar tu base de clientes empresa con datos públicos actualizados (teléfono, web, si el local sigue abierto) reduce rebotes y llamadas perdidas.
• Control de la red de puntos de venta. Un fabricante o una franquicia revisa cómo aparecen sus distribuidores y locales en Maps: nombre, categoría, valoración y reseñas, para detectar fichas mal configuradas.
• Datos en tu infraestructura. Como todo corre en tu equipo o tu servidor, el resultado no pasa por un proveedor externo, algo que agradece el área de seguridad y de cumplimiento.

Ejemplos por rubro

Cómo instalarlo y hacer tu primer scrape

Necesitas Docker Desktop. Python 3 es opcional y no instala nada extra.

git clone https://github.com/Mahanaicoach/google-maps-scraper-kit.git
cd google-maps-scraper-kit
docker compose up -d
curl http://localhost:8080/api/v1/jobs

Si el último comando devuelve [] o null, el motor está listo. La primera vez descarga la imagen de gosom: en nuestra prueba fueron 2,06 GB, porque trae Chromium dentro.

Primer scrape con la ciudad geocodificada automáticamente:

python3 scripts/scrape.py "dentistas en Quito" --city "Quito, Ecuador" --depth 5

Toda la ciudad, por encima del tope de unos 120 resultados por búsqueda, en una cuadrícula de 3 x 3 sin duplicados:

python3 scripts/scrape.py "ferreterías en Guayaquil" --city "Guayaquil, Ecuador" --grid 3

Varias búsquedas en un solo trabajo, una por línea en un archivo:

python3 scripts/scrape.py --keywords-file mis-busquedas.txt --city "Cuenca, Ecuador" --socials

En Windows usa py scripts/scrape.py. El script en bash scrape.sh necesita WSL2 o Git Bash.

Con Claude Code

Abre la carpeta del kit con claude y la skill y los comandos se cargan solos. También puedes instalar solo la skill en tu agente con npx skills add mahanaicoach/google-maps-scraper-kit. Luego basta con pedirlo:

Comprueba que el motor está levantado, busca gimnasios en Quito con profundidad 5 y dame una tabla con nombre, teléfono y web.

La skill obliga al agente a guardar el CSV en disco y mostrar solo unas filas de muestra, en lugar de volcar datos personales al chat. Si es la primera vez que usas skills, empieza por qué son las skills de Claude Code y cómo se instalan.

Lo que encontramos al probarlo en Windows

Lo instalamos y lo ejecutamos de verdad en un PC con Windows 11, Docker Desktop 29.2.1 y Python 3.14.3, con el kit v1.1.0 y el motor v1.18.1. Hicimos dos búsquedas pequeñas en Quito (depth 2) para no forzar los límites de Google.

Lo que nos llevamos de la prueba:

• El rubro manda más que la herramienta. Casi ninguna ferretería de Quito tiene web, así que no hay de dónde sacar correos: el teléfono es el dato útil. Las clínicas dentales sí tienen web y el 41 % publica un correo. Antes de planear una campaña por correo, mira cuántos negocios de tu rubro tienen web.
• La primera vez descarga 2,06 GB. La imagen del motor trae Chromium y pesa bastante más que "unos cientos de MB". Después arrancó en 29 segundos.
• El puerto 8080 suele estar ocupado. En nuestro PC lo usaba pgAdmin. La solución es la que trae el kit: un archivo .env con SCRAPER_PORT=8090.
• Con el motor vacío, la API devuelve null, no []. Si lo compruebas con curl, cualquiera de las dos respuestas significa que el motor está listo.
• Categorías en inglés con el script. scrape.py envía "lang": "en" al motor. Por la API con "lang": "es" salen en español, como se ve en la tabla.
• CSV con tildes rotas fuera de Excel. En Windows el script guarda el CSV en la codificación del sistema (cp1252), no en UTF-8. Excel lo abre bien; Google Sheets u otras herramientas muestran mal las tildes. El CSV en bruto que descarga la API sí viene en UTF-8.
• La tabla de la portada del motor sale vacía. En la v1.18.1 la interfaz web de localhost:8080 no lista los trabajos aunque hayan terminado; sí aparecen en /jobs y en /api/v1/jobs.

También ejecutamos sus pruebas y sus funciones de extracción sin red. Las 11 pruebas del kit pasan, y la búsqueda de páginas de contacto tiene un punto débil en español.

• Páginas de contacto en español: a medias. La segunda pasada de correos busca enlaces que contengan contact o about. /contacto entra por coincidencia parcial, pero /nosotros o /quienes-somos no, y las rutas de respaldo que prueba son /contact, /contact-us, /about y /about-us. En nuestra prueba con ferreterías esa segunda pasada no añadió ningún correo.
• Correos de dominios gratuitos. El extractor ordena primero los correos del dominio del negocio, pero también conserva los de Gmail u Hotmail que aparezcan en la página. En pymes suele ser el correo real del dueño, lo que lo convierte en dato personal (lo vemos abajo).

Lo legal, sin dramatismo y sin atajos

El propio README lo dice sin rodeos: hacer scraping de Google Maps va contra los términos de Google, y los teléfonos y correos son datos personales. Eso no convierte en ilegal cada uso, pero sí obliga a hacerlo bien. Esto es información general, no asesoría legal; para una campaña grande consulta con un abogado de tu país.

Los términos de Google

Los Términos adicionales de Google Maps (última modificación: 4 de junio de 2025) prohíben, como condición de la licencia de uso, "descargar en masa o crear feeds masivos del contenido" y usar Google Maps para crear o ampliar "una base de datos de fichas de negocio, una lista de correo o una lista de telemarketing" destinada a un servicio que sustituya a Google Maps.

En la práctica, el riesgo es contractual y técnico: Google puede limitar tu IP durante minutos u horas (el kit lo advierte y recomienda proxies) o bloquear el acceso. No es un delito por sí mismo, pero revender la base de datos o montar un directorio con ella es justo lo que esos términos persiguen. Si tu empresa necesita estos datos de forma continua y a gran escala, la vía contractual limpia es la API oficial de Google Places, de pago y con sus propias condiciones.

Ecuador: Ley Orgánica de Protección de Datos Personales (LOPDP)

• Los datos de una empresa no son datos personales; los de una persona sí. El teléfono de una sociedad anónima no está protegido por la LOPDP, pero en Ecuador muchísimos negocios son personas naturales con RUC: el celular y el Gmail que aparecen en su ficha son datos personales de alguien.
• Que sea público no basta. La Superintendencia de Protección de Datos Personales respondió en 2026 (oficio SPDP-IRD-2026-0242-O) que la información de fuentes de acceso público "no habilita su uso libre": el nuevo fin debe ser compatible con el motivo por el que se publicó, y se aplican los principios de finalidad, proporcionalidad y minimización (resumen de NMS Law). Ofrecer un producto a un negocio por el teléfono que el propio negocio publicó para recibir clientes es defendible; cruzar esos datos para perfilar a su dueño, no.
• Derechos y oposición. La persona puede pedirte de dónde sacaste sus datos y oponerse a recibir mercadotecnia directa. Necesitas una lista de exclusión que respetes de verdad.
• Multas. El reglamento de cálculo de multas (Resolución SPDP-SPD-2025-0022-R, julio de 2025) fija para empresas privadas entre el 0,1 % y el 0,7 % del volumen de negocio en infracciones leves y entre el 0,7 % y el 1 % en graves (resumen de NMS Law).

Europa (GDPR) y EE. UU.

• GDPR: si los datos son de personas en la UE, necesitas una base jurídica (normalmente el interés legítimo del artículo 6.1.f, con su ponderación documentada) y debes informar a la persona de dónde sacaste sus datos (artículo 14). Dos casos reales: en Polonia, Bisnode recibió una multa de más de 943.000 zlotys por no informar a los empresarios cuyos datos tomó de registros públicos, y en 2023 el Tribunal Supremo Administrativo confirmó que esa obligación existía (UODO). En Francia, la CNIL multó con 240.000 € a KASPR en diciembre de 2024 por recopilar contactos de LinkedIn sin base legal, guardarlos demasiado tiempo e informar tarde (CNIL). Además, el envío de correos comerciales en frío tiene reglas propias en cada país europeo.
• EE. UU.: el kit cita CAN-SPAM para correo (remitente veraz, dirección física y una forma de darse de baja que funcione) y CCPA en California. Para llamadas y SMS a celulares, revisa también la TCPA, que es estricta con los sistemas automáticos.

Si tu proyecto toca varias de estas leyes, en nuestra guía de riesgos legales de las apps hechas con IA tienes el mapa completo de EE. UU., Europa y Ecuador.

Checklist de uso responsable

• Usa los datos para prospección B2B puntual y verificada, no para revender la base ni publicarla.
• Guarda solo los 8 campos que necesitas (el kit ya descarta los demás) y borra lo que no conviertas en un plazo definido.
• En el primer contacto di quién eres, de dónde sacaste el dato y cómo darse de baja. Mantén esa lista de exclusión.
• Nada de envíos masivos automáticos: un mensaje relevante a un negocio concreto, no spam.
• Mantén el motor en 127.0.0.1. No tiene autenticación; exponerlo a internet es regalar tu scraper y tus resultados.
• Una búsqueda a la vez, depth 5 para empezar, y proxies solo si de verdad vas a hacer trabajos grandes.

Errores frecuentes

Preguntas frecuentes

¿Es gratis? Sí. Kit y motor tienen licencia MIT y no hay créditos ni suscripciones. Solo pones tu equipo y tu conexión.

¿Necesito una clave de la API de Google Maps? No. El motor usa un navegador headless contra Google Maps, sin API ni facturación. Precisamente por eso aplican los términos de uso de Google Maps y no los de la API.

¿Cuántos negocios saca por búsqueda? Unos 120, que es el tope de Google Maps. Con --grid 3 divide la ciudad en 9 zonas y quita duplicados.

¿Saca el correo de todos los negocios? No. Solo de los que tienen web y publican un correo en ella. Cuenta con correos en una parte de las filas, no en todas.

¿Es legal hacer scraping de Google Maps? Incumple los términos de Google, lo que es un riesgo contractual, no un delito por sí mismo. Lo que sí está regulado por ley es qué haces con los datos personales que obtienes: ahí aplican la LOPDP en Ecuador, el GDPR en Europa y CAN-SPAM o CCPA en EE. UU.

¿Lo puedo usar sin Claude Code? Sí. scripts/scrape.py funciona desde cualquier terminal en Windows, macOS y Linux.

Conclusión

Google Maps Scraper Kit pone en manos de cualquier empresa, de una ferretería de barrio a una cadena nacional, una herramienta de prospección y estudio de mercado que antes costaba suscripciones o tardes enteras copiando datos. Es gratis, MIT y se queda en tu equipo. Úsalo para encontrar a quién venderle y entender tu mercado, cuida los datos personales como si fueran tuyos, y no conviertas los resultados en una base para revender.

Si buscas más herramientas open source que se conectan a Claude Code, mira OpenSEO, la alternativa a Semrush y Ahrefs.