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

DrProspect es un CLI en Python que busca en la API de Google Places (New) sobre una malla hexagonal Uber H3, con archivos checkpoint para reanudar corridas largas sin filas duplicadas.

Especificación

• ProjectSprint.md con el flujo objetivo: búsqueda por keyword por celda hex → extraer nombre, teléfono, sitio, calificación, reseñas y coordenadas → append a CSV.
• Formato JSON de checkpoint definido para deduplicación y reanudación tras interrupción.
• Campos requeridos y consultas de ejemplo (negocios de mascotas, seguridad privada) para pruebas en CDMX y Guadalajara.

Módulos centrales (build de un día)

• hexgrid.py — genera centros H3 y mapea resolución a radio de búsqueda con la API h3-py.
• places_client.py — cliente Text Search con field masks, paginación y extracción estructurada de lugares.
• checkpoint.py — lee/escribe estado checkpoint JSON y hace append deduplicado a CSV.
• prospector.py — orquestador CLI que conecta malla → llamadas API → CSV → actualizaciones de checkpoint.

Documentación, validación y muestras

• requirements.txt, README.md con setup y uso, y test_api.py para validar API keys antes de una corrida completa.
• CSVs de muestra commiteados de pasadas de prospección de mascotas y seguridad privada.
• Documentación de cómo cambiar keywords, resolución H3 y área delimitadora en el README.