LeadHunter v2 - Autonomous Google Maps Lead Hunter

Zero API keys required. Uses Playwright browser automation, smart templates, and Cheerio for website analysis. Only needs a free Google Sheets service account.

Quick Start

# 1. Install dependencies
npm install

# 2. Install Playwright browser
npx playwright install chromium

# 3. Copy environment template
cp .env.example .env

# 4. Fill in Google Sheets config (see below)

# 5. Hunt leads
node dist/index.js hunt -k "Real Estate" -l "Karachi" -n 50

Commands

Hunt Leads

node dist/index.js hunt -k <keyword> -l <location> -n <max_results> [--dry-run]

Examples:

# Find 100 restaurants in New York
node dist/index.js hunt -k "Restaurant" -l "New York" -n 100

# Find 50 real estate agencies in Karachi
node dist/index.js hunt -k "Real Estate" -l "Karachi" -n 50

# Dry run without saving to sheets
node dist/index.js hunt -k "Dentist" -l "London" -n 20 --dry-run

What Uses What (No External APIs!)

Component	Technology	API Key Needed?
Google Maps scraping	Playwright (browser automation)	No
Website analysis	Cheerio (HTML parsing)	No
Outreach messages	Smart templates (12 templates, context-aware)	No
Lead scoring	Algorithm (rule-based scoring)	No
Data storage	Google Sheets API	Free service account

Configuration

# Google Sheets (only requirement)
GOOGLE_SHEETS_SPREADSHEET_ID=your_spreadsheet_id_here
GOOGLE_SHEETS_CREDENTIALS_PATH=./credentials/service-account.json

Google Sheets Setup

1. Go to Google Cloud Console
2. Create a Service Account
3. Download the JSON key file
4. Save as credentials/service-account.json
5. Create a Google Sheet and share it with the service account email (from the JSON)
6. Copy the Spreadsheet ID from the URL

How It Works

Playwright Browser → Google Maps Search → Scroll & Extract
                          ↓
              Click each business for details
              (website, phone, address, coords)
                          ↓
              Cheerio parses each website
              (SEO, mobile, CTAs, WhatsApp, trust)
                          ↓
              Smart template engine generates
              personalized outreach messages
                          ↓
              Lead scoring algorithm (1-10)
                          ↓
              Save to Google Sheets

Website Analysis Checks

• SEO: Title, meta description, viewport, structured data
• Content: Word count, images, headings
• Contact: Phone, email, WhatsApp, contact page
• Trust: SSL, social links, testimonials, certifications
• UX: CTA buttons, navigation, mobile responsiveness

Lead Scoring (1-10)

Factor	Points
No website (high opportunity)	0-3
Website quality issues	0-2
Business rating (4.5+ = max)	0-2
Review count (100+ = max)	0-1
Digital presence (phone, address)	0-1
Business operational status	0-1

Project Structure

leadhunter/
├── src/
│   ├── index.ts                     # CLI
│   ├── orchestrator.ts              # 5-phase workflow
│   ├── config/index.ts              # Config loader
│   ├── models/lead.ts               # Lead types
│   ├── services/
│   │   ├── google-maps.ts           # Playwright scraper
│   │   ├── website-analyzer.ts      # Cheerio analysis
│   │   ├── ai-outreach.ts           # Template engine
│   │   ├── lead-scorer.ts           # Scoring algorithm
│   │   └── google-sheets.ts         # Sheets API
│   └── utils/
│       ├── logger.ts                # pino logging
│       ├── retry.ts                 # Exponential backoff
│       ├── rate-limiter.ts          # Concurrency control
│       └── duplicate-detector.ts    # Deduplication
├── credentials/                     # Service account JSON
├── .env.example
├── package.json
└── tsconfig.json

Dependencies

• playwright - Browser automation for Google Maps scraping
• cheerio - HTML parsing for website analysis
• googleapis - Google Sheets API (free)
• commander - CLI interface
• pino - Structured logging