🗺️ Google Maps AI Agent

Conversational AI agent that extracts and enriches business leads from Google Maps through natural language chat.

Simply chat with the AI: "Find me 100 dental clinics in Los Angeles" and watch it automatically scrape, enrich, and organize leads into Google Sheets.

📋 Table of Contents

• Overview
• Key Features
• How It Works
• System Architecture
• Tech Stack
• Prerequisites
• Installation
• Configuration
• Usage Examples
• Data Fields
• Enrichment Process
• Troubleshooting
• Best Practices
• License

🎯 Overview

Google Maps AI Agent is an intelligent conversational system that transforms Google Maps into a powerful B2B lead generation tool. Instead of manually searching and copying business data, simply chat with an AI agent that understands your requirements and automates the entire process.

What Makes This Special?

Unlike traditional scrapers with rigid forms, this system uses:

• 🤖 Natural Language Interface - Chat naturally like talking to a human assistant
• 🧠 AI-Powered Understanding - GPT-4o interprets your requests intelligently
• 🔄 Automatic Enrichment - Finds emails and company backgrounds automatically
• 📊 Smart Organization - Structures data perfectly in Google Sheets
• ⚡ Real-Time Processing - Watch leads populate as you chat

Who Is This For?

• 💼 Sales Teams - Build targeted prospect lists by location and niche
• 📞 Cold Callers - Get phone numbers and business info instantly
• 📧 Email Marketers - Extract contacts with email enrichment
• 🏢 B2B Agencies - Research local businesses for clients
• 🚀 Entrepreneurs - Find potential customers or partners in any area

✨ Key Features

🗣️ Conversational Interface

• Natural language input: "Find 50 restaurants in NYC"
• No complex forms or parameters
• AI understands context and intent
• Clarifying questions when needed
• Multi-turn conversations

🔍 Intelligent Google Maps Scraping

• Searches via Serper.dev Google Maps API
• Handles pagination automatically
• Extracts comprehensive business data
• Geographic targeting with coordinates
• Filters by location, type, and niche

📧 Automatic Email Enrichment

• Perplexity AI finds company emails
• Scrapes from websites automatically
• Background research on each business
• Validates and formats data
• Updates Google Sheets in real-time

📊 Structured Data Export

• Organized Google Sheets storage
• UUID tracking for each lead
• Clean, CRM-ready format
• Automatic deduplication
• Export-friendly structure

🔄 Two-Stage Workflow

• Stage 1: AI chat → Google Maps scraping → Initial data save
• Stage 2: Auto-triggered enrichment → Email finding → Data update
• Fully automated pipeline
• No manual intervention required

🔄 How It Works

User Experience

You: "Extract info for 100 dental clinics in Los Angeles"

AI Agent: "I'll search for dental clinics in Los Angeles. Starting now..."
         [Searches Google Maps]
         [Finds 100+ results across multiple pages]
         [Saves to Google Sheets automatically]

AI Agent: "✅ Found and saved 97 dental clinics to your sheet!"

[Background process automatically starts]
         [Enriches each lead with email and background]
         [Updates sheet with enriched data]

Technical Flow

User Chat Input
     ↓
GPT-4o AI Agent
     ↓
Map Search Tool (Serper.dev)
     ↓
Extract Business Data
     ↓
Call Sub-Workflow
     ↓
Generate UUID
     ↓
Save to Google Sheets
     ↓
[Automatic Trigger]
     ↓
Google Sheets Detects New Row
     ↓
Perplexity AI Enrichment
     ↓
Find Email & Background
     ↓
Update Sheet with Enriched Data

🏗️ System Architecture

Main Workflow: Chat Agent

┌─────────────────────────────────────────────────────────────┐
│                    CHAT INTERFACE                            │
│              (User converses with AI)                        │
└───────────────────────┬─────────────────────────────────────┘
                        │
                        ↓
┌─────────────────────────────────────────────────────────────┐
│                   AI AGENT (GPT-4o)                          │
│        • Understands natural language requests               │
│        • Plans multi-step search strategy                    │
│        • Manages pagination and iteration                    │
│        • Calls tools intelligently                           │
└───────────────────────┬─────────────────────────────────────┘
                        │
            ┌───────────┴──────────┐
            ↓                      ↓
┌─────────────────────┐  ┌─────────────────────┐
│  MAP SEARCH TOOL    │  │ WORKFLOW TOOL       │
│  (Serper.dev API)   │  │ (Sub-workflow call) │
├─────────────────────┤  ├─────────────────────┤
│                     │  │                     │
│ • Query: "q"        │  │ • JSON data input   │
│ • Location: "ll"    │  │ • UUID generation   │
│ • Page: number      │  │ • Sheet append      │
│ • Returns:          │  │ • Returns: "ok"     │
│   - Name            │  │                     │
│   - Address         │  │                     │
│   - Phone           │  │                     │
│   - Website         │  │                     │
│   - Rating          │  │                     │
│   - Hours           │  │                     │
│                     │  │                     │
└──────────┬──────────┘  └──────────┬──────────┘
           │                        │
           └───────────┬────────────┘
                       │
                       ↓
           ┌───────────────────────┐
           │   GOOGLE SHEETS       │
           │   Initial Data Saved  │
           └───────────────────────┘

Sub-Workflow: Enrichment Process

┌─────────────────────────────────────────────────────────────┐
│              GOOGLE SHEETS TRIGGER                           │
│         (Monitors for new rows every minute)                 │
└───────────────────────┬─────────────────────────────────────┘
                        │
                        ↓
┌─────────────────────────────────────────────────────────────┐
│                      FILTER                                  │
│        • Exclude header row (Name ≠ "Name")                  │
│        • Only process rows with data                         │
└───────────────────────┬─────────────────────────────────────┘
                        │
                        ↓
┌─────────────────────────────────────────────────────────────┐
│                  LOOP OVER ITEMS                             │
│           (Process each lead individually)                   │
└───────────────────────┬─────────────────────────────────────┘
                        │
                        ↓
┌─────────────────────────────────────────────────────────────┐
│             PERPLEXITY AI ENRICHMENT                         │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  Prompt: "Get email and background for [Company] at         │
│          [Address], reference website: [URL]"                │
│                                                              │
│  Returns JSON:                                               │
│  {                                                           │
│    "Email": "[email protected]",                           │
│    "Background": "Company description..."                    │
│  }                                                           │
│                                                              │
└───────────────────────┬─────────────────────────────────────┘
                        │
                        ↓
┌─────────────────────────────────────────────────────────────┐
│                  UPDATE GOOGLE SHEETS                        │
│          (Match by UUID, update Email & Background)          │
└─────────────────────────────────────────────────────────────┘

🛠️ Tech Stack

📦 Prerequisites

Required Accounts & API Keys

API Keys Needed

• ✅ OpenAI API Key
• ✅ Serper.dev API Key
• ✅ Perplexity API Key
• ✅ Google Sheets OAuth credentials

Technical Requirements

• n8n instance (v1.0+)
• Modern web browser
• Stable internet connection

🚀 Installation

Step 1: Download Workflows

Download these two JSON files:

1. Google map ai agent.json (Main workflow)
2. Sub-Workflow of Google map lead ai agent.json (Helper workflow)

Step 2: Import Main Workflow

1. Open your n8n instance
2. Click "Workflows" → "Import from File"
3. Select Google map ai agent.json
4. Click "Import"

Step 3: Import Sub-Workflow

1. Repeat the import process
2. Select Sub-Workflow of Google map lead ai agent.json
3. This workflow will be called by the main workflow

Step 4: Create Google Sheet

1. Go to https://sheets.google.com/

2. Create new spreadsheet: "Leads Google map ai agent"

3. Create headers in row 1:

   UUID | Name | Address | Number | Website | Rating | Opening Hours | Email | Background
   

4. Copy the spreadsheet ID from URL:

   https://docs.google.com/spreadsheets/d/SPREADSHEET_ID_HERE/edit
   

Step 5: Configure API Keys

See Configuration section below for detailed setup.

Step 6: Link Sub-Workflow

1. In main workflow, find "Call n8n Workflow Tool" node
2. Update workflowId to your imported sub-workflow ID
3. Find workflow ID in URL when viewing sub-workflow:

   /workflow/YOUR_WORKFLOW_ID
   

Step 7: Activate Both Workflows

1. Open main workflow → Toggle "Active" (green)
2. Sub-workflow can remain inactive (called by main)
3. Chat interface is now live!

⚙️ Configuration

1. OpenAI API Key

Node: "OpenAI Chat Model"

1. Get API key from https://platform.openai.com/api-keys
2. In n8n: Settings → Credentials
3. Add "OpenAi account" credential
4. Paste API key
5. Select in node

Model: GPT-4o (recommended for best performance)

2. Serper.dev API Key

Node: "Map Search Tool"

1. Sign up at https://serper.dev/
2. Get API key from dashboard
3. In node, find Headers section
4. Update X-API-KEY value with your key

Current in workflow:

"X-API-KEY": "c2305ea10799e51fd2b15865df14caac6ba573eb"

Replace with:

"X-API-KEY": "YOUR_SERPER_API_KEY"

Parameters explained:

• q: Search query (provided by AI)
• ll: Location coordinates (default: New York area)
• page: Pagination (AI handles automatically)
• hl: Language (en = English)
• location: Country filter
• gl: Geographic location code (us = USA)

3. Perplexity API Key

Node: "Message a model1"

1. Get API key from https://www.perplexity.ai/settings/api
2. In n8n: Settings → Credentials
3. Add "Perplexity account" credential
4. Paste API key
5. Select in node

Model: Sonar (optimized for research tasks)

4. Google Sheets OAuth

Nodes:

• "Google Sheets Trigger"
• "Append row in sheet" (in sub-workflow)
• "Google Sheets" (update node)

1. In n8n: Settings → Credentials

2. Add "Google Sheets OAuth2 API"

3. Follow OAuth flow to authorize

4. Grant permissions for:

   • Read spreadsheets
   • Write spreadsheets
   • Create/update rows

5. Update all Google Sheets nodes:

   • Set credential
   • Select your spreadsheet
   • Select "Sheet1" (or your sheet name)

5. Update Spreadsheet IDs

In Main Workflow:

Find "Google Sheets Trigger" node:

"documentId": "1R4PGBIBihrNCfj0olbDT2p3jbtWCwYVlCgKU6Z3rf48"  // Your ID
"sheetName": "gid=0"  // Sheet1

Find "Google Sheets" (update node):

"documentId": "1R4PGBIBihrNCfj0olbDT2p3jbtWCwYVlCgKU6Z3rf48"  // Your ID

In Sub-Workflow:

Find "Append row in sheet" node:

"documentId": "1R4PGBIBihrNCfj0olbDT2p3jbtWCwYVlCgKU6Z3rf48"  // Your ID

📖 Usage Examples

Example 1: Simple Search

You:

Find 50 coffee shops in Seattle

AI Agent:

• Searches Google Maps for coffee shops in Seattle
• Extracts all business data
• Saves to Google Sheets
• Returns: "✅ Found and saved 47 coffee shops!"

Example 2: Specific Niche

You:

Extract info for 100 dental clinics in Los Angeles

AI Agent:

• Searches: "Dental Clinic Los Angeles"
• Handles pagination (100 results = 5 pages)
• Saves each page to sheets automatically
• Background enrichment starts automatically

Example 3: Multiple Locations

You:

I need restaurants in Manhattan, specifically Italian ones

AI Agent:

• Refines query: "Italian Restaurant Manhattan"
• Searches with New York coordinates
• Extracts comprehensive data
• Enriches with emails and backgrounds

Example 4: Follow-up Requests

You:

Now find 30 more in Brooklyn

AI Agent:

• Remembers context (restaurants)
• Searches Brooklyn area
• Continues adding to same sheet
• Maintains conversation flow

📊 Data Fields

Fields Scraped from Google Maps

Fields Added by Enrichment

🔄 Enrichment Process

How Emails Are Found

1. Trigger: New row detected in Google Sheets

2. Filter: Skip header row and empty entries

3. Loop: Process each lead individually

4. Perplexity Query:

   Get the email and background for [Company Name] at [Address], 
   reference website: [Website URL]
   

5. AI Research:

   • Visits company website
   • Scrapes contact pages
   • Finds email patterns
   • Researches company info

6. JSON Response:

   {
     "Email": "[email protected]",
     "Background": "Family-owned pizza restaurant since 1985..."
   }
   

7. Update Sheet: Matches by UUID, updates Email & Background columns

Enrichment Speed

• Processing: ~5-10 seconds per lead
• Batch: 60 leads in ~5-10 minutes
• Automatic: No manual intervention needed

🐛 Troubleshooting

Issue: Chat Interface Not Loading

Error: Webhook URL doesn't open

Solution:

1. Verify main workflow is Active
2. Click "When chat message received" node
3. Copy "Production URL"
4. Open URL in new browser tab
5. Should see chat interface

Issue: No Results from Map Search

Error: AI says "Found 0 results"

Solution:

1. Check Serper.dev API key is valid
2. Verify you have credits remaining
3. Try broader search terms
4. Check location parameter (ll) is set
5. Test query directly at serper.dev

Issue: Data Not Saving to Sheets

Error: Workflow runs but sheet empty

Solution:

1. Verify Google Sheets credentials
2. Check spreadsheet ID is correct
3. Ensure sheet has proper headers
4. Test sub-workflow independently
5. Review execution logs for errors

Issue: Email Enrichment Not Working

Error: Email and Background stay empty

Solution:

1. Check Perplexity API key is valid
2. Verify Google Sheets Trigger is active
3. Check filter conditions aren't too restrictive
4. Ensure website URLs are valid
5. Monitor trigger polling (every 1 minute)
6. Review Perplexity AI response in logs

Issue: UUID Not Generating

Error: UUID column empty or errors

Solution:

1. Check Code node in sub-workflow
2. Verify UUID v7 generation function
3. Test with simpler UUID generation
4. Ensure JSON parsing is correct

Issue: AI Agent Not Understanding Requests

Error: AI gives irrelevant responses

Solution:

1. Use clear, specific language
2. Include: quantity, niche, location
3. Example: "Find 50 dentists in Miami"
4. Check system prompt in AI Agent node
5. Verify GPT-4o model is selected
6. Review conversation memory settings

💡 Best Practices

Effective Prompts

✅ Good:

• "Extract 100 dental clinics in Los Angeles"
• "Find 50 Italian restaurants in Manhattan"
• "Get coffee shops in Seattle, 30 results"

❌ Avoid:

• "Find some businesses" (too vague)
• "Restaurants" (missing location)
• "Get me leads" (not specific)

Cost Optimization

Serper.dev (Biggest cost):

• Each search = 1 credit
• 100 results = ~5 searches (pagination)
• $50/mo = 5,000 searches = ~100,000 leads

OpenAI GPT-4o:

• ~$0.01-0.03 per chat interaction
• Optimize: Ask for all leads in one message

Perplexity AI:

• ~$0.005 per enrichment
• 100 leads = ~$0.50
• Consider enriching only high-quality leads

Data Quality

Before Running:

• Define clear target criteria
• Use specific location names
• Include business type/niche

After Scraping:

• Spot-check first 10 results
• Verify data accuracy
• Remove duplicates if any
• Export to CRM

Scaling Tips

For 1,000+ Leads:

1. Break into smaller batches (100-200)
2. Use multiple conversations
3. Monitor API rate limits
4. Let enrichment complete between batches
5. Export and backup regularly

🎯 Use Cases

1. Local Business Prospecting

Target specific niches in geographic areas:

• "Find 200 plumbers in Chicago"
• "Get auto repair shops in Texas"

2. Restaurant Database Building

Create comprehensive F&B lists:

• "Extract all sushi restaurants in Los Angeles"
• "Find Italian restaurants, NYC, 150 results"

3. Healthcare Provider Lists

Build medical practice databases:

• "Dental clinics in Florida, 500 leads"
• "Chiropractors in California"

4. Retail Location Research

Map out retail opportunities:

• "Coffee shops in Seattle metro area"
• "Boutique clothing stores in Manhattan"

5. Service Provider Sourcing

Find local service businesses:

• "HVAC companies in Phoenix"
• "Electricians in Boston area"

📄 License

This project is licensed under the MIT License.

What This Means

✅ Commercial use allowed
✅ Modification allowed
✅ Distribution allowed
✅ Private use allowed
⚠️ No warranty or liability

🌟 Acknowledgments

Built with powerful tools:

• n8n - Workflow automation
• OpenAI GPT-4o - Conversational AI
• Serper.dev - Google Maps API
• Perplexity AI - Email enrichment
• Google Sheets - Data storage

🚀 Roadmap

Planned Features

• Export to CSV/Excel
• CRM integration (HubSpot, Salesforce)
• Advanced filtering options
• Duplicate detection
• Email verification
• Social media profile finding
• Bulk search from file upload
• Custom data field extraction
• Schedule automated scraping
• Multi-language support

💬 Support

Get Help

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues

📈 Performance Metrics

Expected Performance:

Made with ❤️ for Sales & Marketing Professionals

⭐ Star this repo if it helps your lead generation!

📢 Share with teams who need automated prospecting!

🔗 Fork and customize for your specific needs!

Ready to generate thousands of leads? Start chatting with your AI agent now! 🗺️