PyLeadFinder

Find and enrich business leads using Google Places API with ZIP code optimization. Optionally includes email extraction via website scraping.

Installation

pip install pyleadfinder

Requirements:

• Python 3.9+
• Google Places API key (get one)

Usage

PyLeadFinder supports three operating modes:

1. API Mode (Default) - For Integration

Returns JSON-serializable dictionaries directly.

from pyleadfinder import leadfinder

results = leadfinder(
    places_api_key="YOUR_KEY",
    queries=["liquor stores"],
    bounds=(45.4, 45.6, -122.8, -122.5),  # (min_lat, max_lat, min_lng, max_lng)
    radius=30
)

# Use the data in your application
for company in results['companies']:
    print(f"{company.name}: {company.email}")

2. CSV Mode - For Spreadsheets

Export data to CSV format for use in Excel, Google Sheets, or other tools.

from pyleadfinder import leadfinder

results = leadfinder(
    places_api_key="YOUR_KEY",
    queries=["coffee shops"],
    bounds=(45.4, 45.6, -122.8, -122.5),
    output_mode="csv"
)

# Outputs: leads.csv

3. KML Mode - For Google My Maps

Output KML files that can be imported directly into Google My Maps.

from pyleadfinder import leadfinder

results = leadfinder(
    places_api_key="YOUR_KEY",
    queries=["restaurants"],
    bounds=(45.4, 45.6, -122.8, -122.5),
    output_mode="kml"
)

# Outputs: leads.kml

How It Works

1. ZIP Code Optimization: Uses hexagonal grid packing to minimize API calls (40-60% reduction).
2. Places Search: Multi-threaded search across optimized locations.
3. Email Extraction: Scrapes company websites for contact info (optional).
4. Export: Generates output based on selected mode.

Arguments

leadfinder(
    # Required
    places_api_key: str,              # Google Places API key
    queries: list[str],               # Search terms like ["restaurants"]
    bounds: tuple,                    # (min_lat, max_lat, min_lng, max_lng)

    # Optional
    output_name: str = "leads",       # Base filename for outputs
    radius: int = 30,                 # Search radius
    radius_unit: str = "miles",       # Unit: "miles", "km", "meters", "yards"
    output_mode: str = "api",         # "api" (default), "csv", or "kml"
    
    # Advanced Options (kwargs)
    excluded_keywords: list = [],     # Keywords to filter out companies/URLs
    num_workers: int = 10,            # Number of threads for parallel processing
    timeout: int = None,              # Operation timeout in seconds (None = no limit)
    scrape_emails: bool = False       # Scrape websites for emails (Default: False)
)

Output Modes

• "api" (default): Returns data in a dictionary, no file output.
• "csv": Generates a CSV file with all company data.
• "kml": Generates a KML file for Google My Maps import.

About the radius parameter

• Smaller radius = better coverage and more complete results.
• Smaller radius = significantly more API calls.
• The ZIP code optimizer uses this radius to determine coverage density.
• Example: radius=10 might require 3-4x more ZIP codes than radius=30.

Output Files

API Mode: No files generated - use the returned dictionary with companies, stats, and map_data.

CSV Mode: Spreadsheet export with columns: name, address, city, state, zip_code, phone, website, emails, latitude, longitude, place_id.

KML Mode: Import directly to Google My Maps.

Examples

See examples/ directory for working examples of all three modes.

License

MIT License - Copyright 2025 Austin Rakowski