Google Maps Scraper Kit

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).

Built as a thin wrapper around gosom/google-maps-scraper by Georgios Komninos (MIT). See 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.

⚠️ 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.

---

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)

• ✅ 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).