workflows/local_business_hunter.md

Workflow: Local Business Hunter (Ideal)

Objective: Automatically discover and research local leads for a specific niche and location with 0 budget.

Required Inputs

• NICHE: The industry or business type (e.g., "Dentist", "Plumber", "HVAC").
• LOCATION: The city or area to target (e.g., "Austin, TX", "London, UK").

Steps

1. Discovery (google_maps_scraper.py)

   • Launch a stealth browser using Playwright.
   • Search Google Maps for NICHE in LOCATION.
   • Scroll through results to find up to 50 businesses.
   • Extract: Name, Website, Phone, Rating, and Review Count.
   • Save to .tmp/raw_leads.json.

2. Enrichment (contact_enricher.py)

   • Read .tmp/raw_leads.json.
   • For each business with a website:
     • Visit the website using httpx and BeautifulSoup.
     • Scrape the homepage and "Contact/About" pages for:
       • Emails (using regex).
       • Facebook URL.
       • Instagram URL.
       • LinkedIn URL.
   • Filter out duplicate or junk entries.

3. Synthesis

   • Combine the scraped data from Google Maps with the enriched contact info.
   • Save the final dataset as leads_NICHE_LOCATION.csv.

Edge Cases

• No Website: If a lead has no website, highlight it as a "High Opportunity" for web design services but skip enrichment.
• CAPTCHA: If blocked, the agent should alert the user to check the IP/proxy or wait.
• Dead Links: Sites that return 404 or connection errors should be marked as "Inactive".