pyleadfinder 0.1.0

Lead generation tool using Google Places API with ZIP code optimization

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