Construyendo DrProspect

DrProspect es una herramienta CLI en Python para prospección de negocios basada en mapas. Dado un keyword y un punto geográfico central, particiona el área de búsqueda en un grid hexagonal Uber H3, consulta la Google Places API (New) en el centro de cada celda y exporta leads calificados a CSV — con un sistema de checkpoint para que corridas interrumpidas se reanuden sin duplicados.

Qué hace

Búsqueda por keyword e industria

La herramienta busca por tipo de negocio o keyword de industria (p. ej. "gyms", "gardening services", "seguridad privada") — alineado con la semántica de text search de Google, no solo nombres exactos de negocio. Esto la hace útil para ventas outbound, investigación de mercado y mapeo competitivo.

Cobertura con grid hexagonal

hexgrid.py usa la librería H3 de Uber para teselar el área alrededor de una coordenada central:

• Convierte lat/lng central a una celda H3 en una resolución elegida (7–11)
• Expande hacia afuera con grid_disk() para un tamaño de anillo configurable
• Devuelve una lista de coordenadas centrales de celda para buscar de forma sistemática

La resolución controla la granularidad: resolución 9 ≈ 174 m de arista por celda (escala de manzana); mayor resolución implica celdas más pequeñas y más llamadas a API pero cobertura más densa.

Extracción de datos

places_client.py llama al endpoint Text Search de Places API con un sesgo de ubicación circular por hexágono. Por cada lugar extrae:

La paginación sigue nextPageToken (hasta 3 páginas / 60 resultados por hexágono). Un delay de 100 ms entre requests evita ráfagas de rate limit.

Exportación CSV y checkpoint

checkpoint.py gestiona salida durable:

• CSV — Agrega filas con un esquema fijo de columnas; crea header en la primera escritura
• Checkpoint JSON — Almacena processed_place_ids y processed_hexagons
• Deduplicación — Omite lugares ya presentes en el checkpoint o CSV existente
• Reanudabilidad — Volver a ejecutar con la misma ruta de salida continúa desde el último estado guardado
• Escrituras bufferizadas — Flush cada 10 lugares nuevos para limitar pérdida de datos en crash

Interfaz CLI

python prospector.py "gyms" --lat 40.7831 --lng -73.9712 -o gyms.csv

Requeridos: término de búsqueda, --lat, --lng. Opcionales: --output, --resolution, --ring-size, --radius, --api-key (o variable de entorno GOOGLE_PLACES_API_KEY). La API key se carga desde .env vía python-dotenv.

Un script test_api.py ejecuta una consulta mínima a Places para verificar conectividad de la API key antes de una corrida completa de prospección.

Corridas reales

El repositorio incluye salida de muestra de campañas de prospección enfocadas en México:

• mx_mascotas.csv / gdl_mascotas.csv — Negocios relacionados con mascotas (nacional y Guadalajara)
• mx_seguridad_privada.csv / gdl_seguridad_privada.csv — Empresas de seguridad privada

Cada par de corridas tiene un .checkpoint.json correspondiente que demuestra el flujo de reanudación.

Stack tecnológico

Sin base de datos ni UI web — la herramienta está diseñada como pipeline scriptable para generación de leads en batch.

Proceso de desarrollo

Diseño del proyecto

ProjectSprint.md capturó la spec inicial: búsqueda por keyword sobre un área particionada en hexágonos, extracción de nombre/teléfono/sitio/calificación/reseñas/ubicación a CSV, con deduplicación y reanudación basada en checkpoint.

Implementación inicial

Build de un solo día en cuatro módulos:

• hexgrid.py — Generación de centros H3 y mapeo resolución-a-radio
• places_client.py — Cliente Text Search con field mask, paginación y extracción de datos del lugar
• checkpoint.py — Checkpoint JSON + append CSV con dedup
• prospector.py — Orquestador CLI que conecta grid → API → CSV → checkpoint

Se agregaron requirements.txt, README.md con docs de setup/uso y test_api.py para validación de API key. Se commitearon corridas de muestra para negocios de mascotas y firmas de seguridad privada en México y Guadalajara.