Documentation

1. Requirements

• Chrome version 114 or later (or any Chromium-based browser: Edge, Brave, Opera, Arc)
• Windows, macOS, or Linux
• A free OpenRouter account for AI outreach generation
• No Node.js, no build step, no npm — the extension loads directly into Chrome

2. Installation

MapScout is distributed as an unpacked Chrome extension. There is no Chrome Web Store listing yet — installation requires Developer Mode.

1. Download and unzip the MapScout extension files to a folder on your computer
2. Open Chrome and navigate to chrome://extensions
3. Enable Developer mode using the toggle in the top-right corner
4. Click Load unpacked
5. Select the folder containing the extension files (the folder with manifest.json at the root)
6. MapScout will appear in your extensions list
7. Click the puzzle piece icon → pin MapScout to your toolbar
8. Navigate to google.com/maps — the extension activates automatically
9. Click the MapScout icon to open the side panel

3. First-Time Setup

On first launch, an onboarding overlay appears. Click Open Settings and fill in the following before capturing leads.

Your Profile

These fields personalise the AI outreach. The more specific you are, the better the emails.

OpenRouter API Key

1. Go to openrouter.ai and create a free account
2. Navigate to API Keys and create a new key
3. Paste the key (starts with sk-or-) into Settings → AI → OpenRouter API Key
4. Click Test Connection — you should see “✓ Connected”
5. Click Save

4. Passive Capture Mode

Passive capture is the recommended mode. The extension monitors your browser URL in the background. Whenever you click into a listing on Google Maps, it waits 900ms for the page to load, then automatically captures and scores the lead.

A badge appears in the bottom-right of the Maps page showing how many leads have been captured this session.

To use passive capture

1. Make sure Auto-scrape mode is OFF in Settings
2. Open Google Maps and search for your target business type and city
3. Click into listings — each one is captured automatically
4. Switch to the MapScout side panel to see leads appear in real time

5. Auto-Scrape Mode

Auto-scrape mode automates the entire capture process. It scrolls the Google Maps results feed, collects all listing URLs, opens each one in a background tab (3 at a time), extracts the data, and closes the tab.

To use auto-scrape

1. Enable Auto-scrape mode in Settings → Scrape Behavior
2. Open Google Maps and run a search (e.g. “cosmetic dentist Austin TX”)
3. Click ▶ Start Scrape in the side panel
4. Watch leads appear in real time. Check the Logs tab for detailed progress
5. After all listings are processed, website audits run automatically for leads above your audit threshold

6. Batch Search Mode

Batch mode runs multiple search queries sequentially without you having to type each one. Use it to cover multiple cities, niches, or both — unattended.

To run a batch search

1. Enable Auto-scrape mode in Settings
2. Go to Settings → Batch Search
3. Enter one search phrase per line, for example:

cosmetic dentist Austin TX
med spa Denver CO
personal injury lawyer Nashville TN

4. Open Google Maps
5. Click ▶ Run Batch
6. The extension navigates the Maps tab to each search URL in sequence and processes each automatically

7. Lead Scoring System

Leads are scored 1–10. The raw point total across all signals is normalised to this scale. Expand any lead card and scroll to “Score breakdown” to see exactly which signals contributed.

Phase 1 — Google Maps Signals

Phase 2 — Website Audit Signals

After running a website audit, these additional signals update the lead’s score:

8. Website Audit

The website audit opens each lead’s website in a hidden background tab, injects an analysis script, and collects 25 data points in under 15 seconds per site.

What it checks

• Platform (WordPress, Wix, Squarespace, Weebly, GoDaddy, Webflow, Duda, Showit, or Unknown)
• Copyright year (detected from © YYYY patterns)
• Booking form presence (button/link text matching)
• Off-site booking links (Zocdoc, Booksy, Vagaro, Mindbody, Calendly, Acuity, etc.)
• Testimonials section
• Before/after gallery
• Email addresses (from mailto: links and body text)
• Owner name (from JSON-LD schema or "Meet Dr. Smith" patterns)
• Mobile viewport meta tag
• SSL (HTTPS vs HTTP)
• Contact form
• Social media links (Facebook, Instagram, TikTok, LinkedIn, X/Twitter)
• Analytics tracking (Google Analytics / GTM / Meta Pixel)
• Clickable phone number (tel: link)
• Business hours text
• Google Map embed
• Video content (YouTube, Vimeo, Loom)
• LocalBusiness JSON-LD schema
• Chat widget (Intercom, Drift, Tidio, LiveChat, Tawk, Crisp, etc.)
• Pop-up / exit intent
• Nav item count
• Page title

To run an audit

Click 🌐 Audit in the controls bar. All leads with a website that score above your audit threshold (default: 5) and haven’t been audited yet will be processed in parallel (4 at a time).

9. AI Outreach Generation

Each lead card has a ✨ Generate AI Outreach button. Click it to produce a full outreach pack tailored to that specific lead.

Prerequisites

• OpenRouter API key saved in Settings → AI
• Your service profile filled in (Settings → Profile)

What it generates

• 3 subject line options (click any to copy)
• Primary cold email (under 150 words, references specific issues found on their site)
• 3-day follow-up email
• LinkedIn message (under 300 characters)
• SMS (under 160 characters)

Model fallback

If the configured model is rate-limited or unavailable, MapScout automatically tries up to 4 fallback models in sequence: Llama 3.3 70B → Gemini Flash → Qwen QwQ → DeepSeek R1. A 600ms pause is inserted between retries.

Common outreach errors

• 401 errorInvalid API key. Re-copy it from openrouter.ai/settings/keys.
• 402 errorNo credits. Add $5 at openrouter.ai or use a free model.
• All models failedFree model rate limits exceeded. Wait 30–60 seconds and retry.
• OpenRouter 404Model ID no longer available as free tier. Change the model in Settings → AI.

10. Exporting Leads

Click ↓ Export in the controls bar to download a CSV file.

• Filename: leads_YYYY-MM-DD.csv
• Encoding: UTF-8 with BOM (renders correctly in Excel and Google Sheets)
• 40 columns covering all Phase 1 and Phase 2 fields
• Sorted by search phrase, then by score descending
• By default, only leads with score 7+ are included. Enable “Export all leads” in Settings to include everything

JSON backup: In Settings → Data, click ↓ Backup JSON to export all lead data as JSON. Use this to archive before clearing storage (chrome.storage.local has a 10 MB limit, ~3,000 leads at ~3 KB per lead).

11. Settings Reference

12. CRM Status & Notes

Each lead card has a status selector and a notes textarea. Both save automatically.

Status values

• new
• researched
• contacted
• replied
• closed

The lead card border colour changes with status so you can see your pipeline at a glance without opening each card.

Notes are free text and auto-saved on blur. They persist across browser restarts via chrome.storage.local.

13. Troubleshooting

For a full list of common issues and their solutions, see the Support page. Key points:

• Check the Logs tab first — it shows exactly what the extension did and where it failed
• Reload the Google Maps tab if the content script doesn’t seem active (look for “Lead Finder connected” in Logs)
• Google periodically updates Maps class names — if extraction breaks after a Maps update, contact support for a selector fix
• Chrome.storage.local has a 10 MB limit. Export and clear data regularly if you capture thousands of leads