title	Leads
emoji	📈
colorFrom	indigo
colorTo	blue
sdk	docker
pinned	false

📈 Lead Scraper — AI-Powered Business Outreach Tool

A full-stack lead generation & outreach platform that scrapes business data from Google Maps and Manta, then uses an LLM (Groq / LLaMA 3.3 70B) to auto-write personalized email and WhatsApp messages — with bulk sending, contact tracking, and CSV export.

---

📑 Table of Contents

• Features
• Tech Stack
• How It Works
• Setup
• Deployment
• Responsible Use
• Author

✨ Features

• Multi-Source Scraping — Google Maps (Playwright) + Manta.com (BeautifulSoup + cloudscraper)
• AI-Generated Messages — Groq LLM writes a personalized outreach message for each lead
• Bulk Email — send AI-crafted emails via Gmail SMTP to all leads at once
• Bulk WhatsApp — open AI-generated WhatsApp messages one-by-one with human-like delays (30–90s) to avoid bans
• Contact Tracking — leads marked as contacted (Email/WhatsApp) with timestamps
• Lead Management — filter, search, edit emails, export CSV, deduplicate
• Responsive UI — works on desktop, tablet, and mobile
• Dark Theme — modern dark UI built with vanilla HTML/CSS/JS

🛠️ Tech Stack

• Backend: Python, Flask
• Scraping: Playwright (Google Maps), BeautifulSoup + cloudscraper (Manta)
• AI: Groq API (LLaMA 3.3 70B)
• Email: Gmail SMTP with App Password
• Frontend: Vanilla HTML, CSS, JavaScript
• Deployment: Docker, Hugging Face Spaces

⚙️ How It Works

1. Search — enter a keyword (e.g. "restaurants") and a location (e.g. "New York")
2. Scrape — the app pulls business listings from Google Maps and/or Manta
3. Review — browse leads in the table, add email addresses, filter by status
4. AI Generate — create a personalized message per lead with one click
5. Send — bulk email via Gmail, or bulk WhatsApp with anti-ban delays
6. Track — contacted leads are marked with WA/EM badges and timestamps

🚀 Setup

1. Clone the repo

git clone https://github.com/AbdulHannan031/lead-scraper.git
cd lead-scraper

2. Install dependencies

pip install -r requirements.txt
playwright install chromium

3. Configure environment variables

cp .env.example .env

Edit .env with your credentials:

GROQ_API_KEY=your_groq_api_key
GMAIL_EMAIL=your_gmail@gmail.com
GMAIL_APP_PASSWORD=your_gmail_app_password

4. Run

python app.py

Open http://localhost:5000 in your browser.

☁️ Deployment

Hugging Face Spaces (Free)

1. Create a new Space with the Docker SDK
2. Add secrets in Settings: GROQ_API_KEY, GMAIL_EMAIL, GMAIL_APP_PASSWORD
3. Push your code to the Space repo

A Dockerfile and render.yaml are included for container / Render deployments too.

⚖️ Responsible Use

This tool is for legitimate B2B outreach and research. You are responsible for complying with:

• Each platform's Terms of Service (Google Maps, Manta, WhatsApp, Gmail)
• Anti-spam laws (e.g. GDPR, CAN-SPAM) — only contact businesses with a lawful basis, honor opt-outs, and don't send unsolicited bulk spam
• Sensible sending rates (the built-in WhatsApp delays exist to keep usage human-like)

Use it to work smarter, not to spam.

👤 Author

Abdul Hannan — Full Stack Developer 📧 abdulhannan03086@gmail.com · 🔗 github.com/AbdulHannan031

If this project helps you, please give it a ⭐ — it helps others find it!