Free, open-source Google Maps scraper for lead generation (Python, no API key, no Docker). Exports name, phone, email, website, rating and Instagram/Facebook/LinkedIn/TikTok/YouTube/X links to CSV. 100 places with emails in 44 s; --grid beats Google's 120 cap. MX email check, ad-pixel detection. Skill for Claude Code, Codex and Cursor.
Python agent-skillsb2b-leadsclaude-codeclaude-skillscodex-skillsemail-extractoremail-scrapergoogle-mapsgoogle-maps-extractorgoogle-maps-leadsgoogle-maps-scrapergoogle-maps-scraper-pythongoogle-maps-scrapinggooglemaps-scraperheadless-chromelead-generationlead-scraperno-api-keypythonweb-scraping
docs: reposition kit, drop wrapper framing, polish README
Mahan Jafari6efd9854da13
diff --git a/CLAUDE.md b/CLAUDE.mdindex d501cf7..9f7aca5 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -39,4 +39,4 @@ If the container isn't running: `docker compose up -d`, then verify `curl http:/Full setup is in `SETUP.md`.## Attribution-This wraps `gosom/google-maps-scraper` (MIT, © Georgios Komninos). Keep `CREDITS.md` + `LICENSE` intact.+The scraping engine is `gosom/google-maps-scraper` (MIT, © Georgios Komninos), run as its official Docker image. Keep `CREDITS.md` and `LICENSE` intact.diff --git a/CREDITS.md b/CREDITS.mdindex c4fe689..2539e52 100644--- a/CREDITS.md+++ b/CREDITS.md@@ -1,7 +1,6 @@# Credits & Attribution-This kit is a **wrapper** around an existing open-source project. The actual scraping engine is **not**-written by this kit's author — full credit goes to the original author.+The Google Maps Scraper Kit runs on an open-source scraping engine by Georgios Komninos.## Upstream project@@ -11,9 +10,9 @@ written by this kit's author — full credit goes to the original author.- **License:** MIT License — Copyright (c) 2023 Georgios Komninos- **Docker image used:** `gosom/google-maps-scraper`-This kit pulls and runs the official published Docker image. It does **not** modify or redistribute the-upstream source code — it only adds a Docker Compose setup, helper scripts, documentation, and a Claude-skill around it. All scraping capability and field extraction come from the upstream project.+The kit runs the official published Docker image and does not modify or redistribute the engine's+source. The kit itself provides the orchestration layer: local deployment, lead-field cleaning, CSV+output, auto-geocoding, batch jobs, social profile enrichment, and the Claude skill and commands.## Upstream license (reproduced as required by MIT)@@ -41,5 +40,4 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THESOFTWARE.```-If you found this useful, please **⭐ star the upstream repo** to support the original author:-https://github.com/gosom/google-maps-scraper+Support the engine's author by starring the repository: https://github.com/gosom/google-maps-scraperdiff --git a/LICENSE b/LICENSEindex 9ec7d22..48bf7aa 100644--- a/LICENSE+++ b/LICENSE@@ -2,8 +2,8 @@ MIT LicenseCopyright (c) 2026 Mahan (github.com/mahanjafari-dev)-This license covers the "Google Maps Scraper Kit" wrapper (Docker Compose setup,-scripts, documentation, and Claude skill) ONLY. The underlying scraping engine,+This license covers the Google Maps Scraper Kit (Docker Compose setup, scripts,+documentation, and Claude skill). The underlying scraping engine,"google-maps-scraper", is a separate work by Georgios Komninos, licensed under theMIT License (Copyright (c) 2023 Georgios Komninos) — see CREDITS.md.diff --git a/README.md b/README.mdindex 6de5652..e9ec4b3 100644--- a/README.md+++ b/README.md@@ -1,152 +1,123 @@# Google Maps Scraper Kit<p align="center">- <img src="assets/banner.svg" alt="Google Maps Scraper Kit — run a free Google Maps scraper locally, let Claude drive it on autopilot" width="100%">+ <img src="assets/banner.svg" alt="Google Maps Scraper Kit — local Google Maps lead extraction, operated by Claude" width="100%"></p>-A **plug-and-play kit** that runs a free, open-source Google Maps scraper **on your own computer**-and lets **Claude** drive it on autopilot — give Claude a city + a business type, get back a clean-list of businesses (name, address, phone, website, rating, reviews, lat/lng, emails).+<p align="center">+ <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-0b1220?style=flat-square"></a>+ <img alt="Runs locally" src="https://img.shields.io/badge/runs-100%25%20local-059669?style=flat-square">+ <img alt="Claude Code" src="https://img.shields.io/badge/Claude%20Code-skill%20%2B%20commands-7c3aed?style=flat-square">+ <img alt="No API keys" src="https://img.shields.io/badge/API%20keys-none-334155?style=flat-square">+</p>-Built as a thin wrapper around [**`gosom/google-maps-scraper`**](https://github.com/gosom/google-maps-scraper)-by **Georgios Komninos** (MIT). See [CREDITS.md](CREDITS.md). This kit adds: a one-command Docker setup,-ready-to-run scripts, and a **Claude skill** so Claude knows exactly how to use the API the right way.+**Local Google Maps lead extraction, operated by Claude.**+Name a business type and a city. Get back a clean, outreach-ready CSV: name, phone, email, website,+category, address, rating, and review count. Optional Instagram, Facebook, and LinkedIn enrichment.-> ⚠️ **Before you scrape — over-use can get your IP temporarily blocked.**-> This runs a real scraper against Google Maps. Light use is fine, but big jobs back-to-back, very high-> `depth`, many keywords, or scheduled runs **without proxies** can make Google **temporarily rate-limit or-> block your IP** (usually clears in minutes–hours; jobs return empty/failed meanwhile). It does **not** ban-> your Google account. Stay safe: **one job at a time, start at `depth 5`, add proxies for large/repeated-> runs.** Scraping Maps is against Google's ToS — use responsibly and follow data law (GDPR/CCPA) for any-> contact data. Full guidance: [Rate limits, bans & responsible use](#️-rate-limits-bans--responsible-use).+Everything runs on your machine. No SaaS, no credits, no API keys.----## What you get--- 🐳 **One-command local setup** — `docker compose up -d` runs the scraper at `http://localhost:8080`.-- 🤖 **A Claude skill** — open this folder in Claude Code and just say *"scrape coffee shops in Austin"*. Claude does create → poll → download → clean results, following best practices automatically.-- 🛠️ **Standalone scripts** — `scripts/scrape.sh` (bash) and `scripts/scrape.py` (Python, no dependencies) if you'd rather not use Claude.-- 🔒 **Safe by default** — the scraper binds to `127.0.0.1` only, secrets are git-ignored, and the skill enforces rate-limit / legal / data-handling guardrails.--## What it scrapes (and what it doesn't)+## Why it exists-- ✅ **Google Maps business listings** → a clean **lead list** by default: `name, phone, email, website, category, address, rating, review count`. The scraper captures ~34 raw fields, but the kit **strips the noise** (geo coordinates, IDs, hours, images, review blobs) so you only get data you can actually use for outreach. Want everything? `scrape.py --full`.-- ➕ **Optional socials** (`--socials`): also pulls each business's **Instagram / Facebook / LinkedIn** by scanning its website. **Token cost: 0** — it runs in code (HTTP + regex), no AI. It only adds ~40–50 tokens *per business* if you later load the rows into an AI chat (≈+2k for 50 leads; nothing if you keep the file on disk). It's slower (one fetch per site) and coverage is partial (only businesses that link socials on their site).-- ❌ **Not** a social-media scraper. It cannot touch Instagram / TikTok / YouTube.+Ask a chat AI to "scrape Google Maps" and it hits a consent wall and JavaScript-rendered pages. Result:+close to zero structured rows. This kit runs a real headless scraping engine locally and gives Claude+a precise operating manual for it. Result: dozens to hundreds of verified listings per query.-## Why use this instead of asking an AI to "just scrape Google Maps"+## Capabilities-Tested head-to-head: a chat AI fetching `maps.google.com` directly hits a **consent wall** and-**JavaScript-rendered** content, so it returns **~0 structured results**. This kit reliably returns-**dozens–hundreds of clean rows per query**. For Google Maps, it's the difference between *can't* and *can*.+| | |+|---|---|+| **Lead-ready output** | The engine captures ~34 raw fields. The kit keeps the 8 you contact and qualify with, and writes a CSV. `--full` keeps everything. |+| **Email extraction** | On by default. Pulls contact emails from each business website. |+| **Social enrichment** | `--socials` finds Instagram, Facebook, and LinkedIn profiles. Runs in code (HTTP + regex), zero AI tokens. |+| **Auto-geocoding** | Type a city name. Coordinates are resolved for you. |+| **Batch jobs** | Many keywords, one job, one CSV. |+| **Claude-native** | A skill plus four slash commands. Claude handles create, poll, download, clean, and present. |+| **Safe defaults** | API bound to `127.0.0.1`, secrets git-ignored, rate-limit and data-law guardrails built into the skill. |----## Quick start (3 steps)+## Quick start++Requires Docker Desktop.```bash-# 1. Start the scraper (needs Docker Desktop)docker compose up -d+```-# 2. Check it's alive — should print a JSON list (probably empty [])-curl http://localhost:8080/api/v1/jobs--# 3a. Scrape with the script…+```bash./scripts/scrape.sh "coffee shops in Austin TX" 30.2672 -97.7431 5--# 3b. …or open this folder in Claude Code and say:-# "Scrape gyms in Miami and give me phones + websites."```-Full instructions: **[SETUP.md](SETUP.md)**. How Claude uses it: **[.claude/skills/google-maps-scraper/SKILL.md](.claude/skills/google-maps-scraper/SKILL.md)**.+Or open the folder in Claude Code and say:++> Scrape gyms in Miami and give me phones and websites.++Detailed setup: [SETUP.md](SETUP.md). Skill reference: [SKILL.md](.claude/skills/google-maps-scraper/SKILL.md).----## Invoking it in Claude Code+## Using it in Claude Code-### Slash commands-| Command | What it does |+| Command | Action ||---|---|-| `/scrape <business> in <city, ST> [depth]` | Run a scrape and get a clean table |-| `/scrape-batch <keywords-file> [--city "City, ST"]` | Scrape many queries in one job |-| `/scrape-setup` | Start the local scraper + health check |+| `/scrape <business> in <city, ST> [depth]` | Run one scrape, return a clean table and CSV |+| `/scrape-batch <keywords-file> [--city "City, ST"]` | Run many queries as one job |+| `/scrape-setup` | Start the engine and run a health check || `/scrape-jobs [list \| delete <id>]` | List or delete jobs |-Example: `/scrape dentists in Denver CO 10`+Plain language works too. The skill triggers on requests like *"build me a lead list of dentists in+Denver, CO"* or *"pull Google Maps listings for plumbers in Phoenix"*. It does not scrape social+platforms directly.-### Or just talk to it — the skill auto-triggers on phrases like:-- "scrape coffee shops in Austin"-- "find all gyms in Miami with phone numbers"-- "build me a lead list of dentists in Denver, CO"-- "pull Google Maps listings for plumbers in Phoenix"+### Without Claude-It intentionally **does not** trigger for social media (Instagram/TikTok) — that's not what it does.+`scripts/scrape.py` is a standalone, dependency-free Python CLI: single queries, batches, geocoding,+socials, CSV output. `scripts/scrape.sh` covers the single-query case in bash.----## ⚠️ Rate limits, bans & responsible use+## Responsible use-The upstream project's guidance (and ours): *"Please use this scraper responsibly and in accordance with-applicable laws and regulations. Unauthorized scraping may violate terms of service."* There's **no-published ban threshold**, so be conservative.+This drives a real scraper against Google Maps. Light use is fine. Heavy use without proxies can get+your IP **temporarily rate-limited** (minutes to hours). Your Google account is not affected.-**What "over-use" looks like** and the risk:-- Big jobs back-to-back, very high `depth`, many keywords at once, or scheduled runs **without proxies**.-- Risk: Google **temporarily rate-limits/blocks your IP** (minutes–hours, then clears). Your Google- **account is not banned**. While blocked, jobs come back `failed` or with empty/short results.--**Block signals to watch:** jobs returning `failed`, suddenly empty results, or far fewer rows than an-identical earlier run. If you see these, **slow down** — pause, lower `depth`, or add proxies.--**Stay safe:**-- One job at a time; start at `depth 5` and raise only as needed.-- Turn on `email` extraction only when you need emails (it's much slower).-- Treat results as **leads to verify**, not a redistributable dataset. Don't resell raw Google data.-- Scraped phones/emails are **personal data** → follow GDPR/CCPA/CAN-SPAM if you store or contact them.--**When to add proxies** (*"For larger scraping jobs, proxies help avoid rate limiting"*): large jobs, many-keywords, repeated/scheduled runs, or after you hit block signals. Set the `proxies` array in the job body:-```json-"proxies": ["socks5://user:pass@host:port", "http://host2:port2"]-```-Types: `socks5`, `socks5h`, `http`, `https` (auth optional). The scraper rotates them automatically.-For reference, upstream measures ~120 places/min at `-c 8 -depth 1`.+- Run one job at a time. Start at `depth 5` and raise only when needed.+- Watch for block signals: `failed` jobs, empty results, or far fewer rows than an identical earlier run.+- Add proxies for large or repeated runs. The engine rotates them automatically:+ ```json+ "proxies": ["socks5://user:pass@host:port", "http://host2:port2"]+ ```+ Supported: `socks5`, `socks5h`, `http`, `https`.+- Scraping Maps is against Google's Terms of Service. Treat output as leads to verify, not a dataset to+ resell. Phones and emails are personal data: follow GDPR, CCPA, and CAN-SPAM.-> Claude's rule here is **warn, don't block**: if you ask for a large scrape, it'll flag the risk and-> suggest proxies, then run it anyway. It only refuses clearly abusive use.+For large requests, Claude flags the risk and suggests proxies, then proceeds. It refuses only clearly+abusive use.----## What's inside+## Project layout```google-maps-scraper-kit/-├── README.md ← you are here-├── SETUP.md ← detailed, copy-paste setup (start here)-├── CLAUDE.md ← auto-loaded instructions for Claude Code-├── CREDITS.md ← attribution to the upstream author (gosom)-├── LICENSE ← MIT (this kit)-├── docker-compose.yml ← runs the scraper locally on :8080-├── .env.example ← config template-├── .gitignore+├── docker-compose.yml local engine on 127.0.0.1:8080+├── .env.example config template├── scripts/-│ ├── scrape.sh ← one-shot bash scraper (single keyword)-│ └── scrape.py ← Python scraper: single, batch, + auto-geocoding (stdlib only)-├── examples/-│ ├── queries.example.json ← reference job body + coordinate cheatsheet-│ └── queries.example.txt ← batch keyword list (one per line)-└── .claude/- ├── settings.json ← pre-approves local commands so Claude runs on autopilot- ├── commands/ ← /scrape, /scrape-batch, /scrape-setup, /scrape-jobs- └── skills/- └── google-maps-scraper/- └── SKILL.md ← THE skill that teaches Claude to use the API well+│ ├── scrape.py Python CLI: single, batch, geocoding, socials, CSV+│ └── scrape.sh bash CLI: single query+├── examples/ sample job body and batch keyword list+├── .claude/+│ ├── settings.json pre-approved local commands for hands-free runs+│ ├── commands/ /scrape, /scrape-batch, /scrape-setup, /scrape-jobs+│ └── skills/google-maps-scraper/SKILL.md+├── CLAUDE.md project instructions for Claude Code+└── SETUP.md full setup guide```-## Credits & license+## License-This kit orchestrates **[google-maps-scraper](https://github.com/gosom/google-maps-scraper)** by-**Georgios Komninos**, used under the MIT License. The kit's own code is MIT licensed too. Full-attribution in **[CREDITS.md](CREDITS.md)**. Please respect Google's Terms of Service and applicable-data-protection law (GDPR/CCPA) when using scraped data — see the Safety section in the skill.+MIT. Scraping engine: [google-maps-scraper](https://github.com/gosom/google-maps-scraper) by Georgios+Komninos (MIT), run as its official Docker image. See [CREDITS.md](CREDITS.md).diff --git a/assets/banner.svg b/assets/banner.svgindex fd01448..37e79d2 100644--- a/assets/banner.svg+++ b/assets/banner.svg@@ -40,7 +40,7 @@<!-- title + subtitle (kept clear of the card on the right) --><text x="300" y="128" class="t" font-weight="800" font-size="44" fill="#f8fafc">Google Maps Scraper Kit</text>- <text x="302" y="170" class="t" font-weight="400" font-size="21" fill="#94a3b8">Run a free Google Maps scraper locally, driven by Claude.</text>+ <text x="302" y="170" class="t" font-weight="400" font-size="21" fill="#94a3b8">Local Google Maps lead extraction, operated by Claude.</text><!-- chips --><g transform="translate(300,200)">