Skip to content

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.

docs: reposition kit, drop wrapper framing, polish README

Mahan Jafari6efd9854da13
diff --git a/CLAUDE.md b/CLAUDE.md
index 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.md
index 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 THE
SOFTWARE.
```
-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-scraper
diff --git a/LICENSE b/LICENSE
index 9ec7d22..48bf7aa 100644
--- a/LICENSE
+++ b/LICENSE
@@ -2,8 +2,8 @@ MIT License
Copyright (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 the
MIT License (Copyright (c) 2023 Georgios Komninos) — see CREDITS.md.
diff --git a/README.md b/README.md
index 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.svg
index 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&#160;Maps scraper locally, driven by Claude.</text>
+ <text x="302" y="170" class="t" font-weight="400" font-size="21" fill="#94a3b8">Local Google&#160;Maps lead extraction, operated by Claude.</text>
<!-- chips -->
<g transform="translate(300,200)">