Building DrProspect

DrProspect is a Python CLI tool for map-based business prospecting. Given a keyword and a geographic center point, it partitions the search area into an Uber H3 hexagon grid, queries the Google Places API (New) at each cell center, and exports qualified leads to CSV — with a checkpoint system so interrupted runs resume without duplicates.

What it does

Keyword search by industry

The tool searches by business type or industry keyword (e.g. "gyms", "gardening services", "seguridad privada") — matching Google’s text search semantics, not just exact business names. This makes it useful for outbound sales, market research, and competitive mapping.

Hexagon grid coverage

hexgrid.py uses Uber’s H3 library to tile the area around a center coordinate:

• Converts center lat/lng to an H3 cell at a chosen resolution (7–11)
• Expands outward with grid_disk() for configurable ring size
• Returns a list of cell-center coordinates to search systematically

Resolution controls granularity: resolution 9 ≈ 174 m cell edges (city-block scale); higher resolution means smaller cells and more API calls but denser coverage.

Data extraction

places_client.py calls the Places API Text Search endpoint with a circular location bias per hexagon. For each place it extracts:

Pagination follows nextPageToken (up to 3 pages / 60 results per hexagon). A 100 ms delay between requests avoids rate-limit bursts.

CSV export & checkpoint

checkpoint.py manages durable output:

• CSV — Appends rows with a fixed column schema; creates header on first write
• Checkpoint JSON — Stores processed_place_ids and processed_hexagons
• Deduplication — Skips places already in the checkpoint or existing CSV
• Resumability — Re-running with the same output path continues from the last saved state
• Buffered writes — Flushes every 10 new places to limit data loss on crash

CLI interface

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

Required: search term, --lat, --lng. Optional: --output, --resolution, --ring-size, --radius, --api-key (or GOOGLE_PLACES_API_KEY env var). API key loads from .env via python-dotenv.

A test_api.py script runs a minimal Places query to verify API key connectivity before a full prospecting run.

Real-world runs

The repo includes sample output from Mexico-focused prospecting campaigns:

• mx_mascotas.csv / gdl_mascotas.csv — Pet-related businesses (national and Guadalajara)
• mx_seguridad_privada.csv / gdl_seguridad_privada.csv — Private security companies

Each run pair has a matching .checkpoint.json demonstrating the resume workflow.

Tech stack

No database or web UI — the tool is designed as a scriptable pipeline for batch lead generation.

Development process

DrProspect is a Python CLI that searches the Google Places API (New) over an Uber H3 hex grid, with checkpoint files so long runs can resume without duplicate rows.

Specification

• Wrote ProjectSprint.md with the target workflow: keyword search per hex cell → extract name, phone, website, rating, reviews, and coordinates → append to CSV.
• Defined checkpoint JSON format for deduplication and resume after interruption.
• Listed required fields and example queries (pet businesses, private security) for Mexico City and Guadalajara test runs.

Core modules (single-day build)

• hexgrid.py — generates H3 cell centers and maps resolution to search radius using the h3-py API.
• places_client.py — Text Search client with field masks, pagination, and structured place extraction.
• checkpoint.py — reads/writes JSON checkpoint state and appends deduplicated rows to CSV.
• prospector.py — CLI orchestrator wiring grid → API calls → CSV → checkpoint updates.

Docs, validation, and samples

• Added requirements.txt, README.md with setup and usage, and test_api.py to validate API keys before a full run.
• Committed sample output CSVs from pet-business and security-firm prospecting passes.
• Documented how to change keywords, H3 resolution, and bounding area in the README.