[opensourcedex]

google-maps-scraper-kit is a free, open source data extraction & web scraping project written in Python and released under MIT. It has 1,432 GitHub stars, 305 forks and 0 open issues, and was last pushed 8 hours ago. On this registry it ranks #94 of 139 tracked projects in Data Extraction & Web Scraping, with 5 head-to-head comparisons available.

What is google-maps-scraper-kit?

Google Maps Scraper Kit is a free, open-source Python tool that turns a business type and a city into an outreach-ready CSV of leads — names, phones, emails, websites, categories, addresses, ratings and review counts — and runs entirely on the user's own machine inside Docker, aimed at freelancers, agencies and sales teams doing cold outreach and B2B lead generation.

What it is

Google Maps Scraper Kit is a free, MIT-licensed, open-source Google Maps scraper for lead generation, written in Python and living in the Google Maps and Google Places scraping niche. It runs locally in Docker with no API keys required, name a business type and a city, and it returns an outreach-ready CSV. It also ships a Claude Code skill that lets AI coding agents drive the scrape in plain English, and it works with Codex, Cursor and any Agent Skills-compatible tool.

The concrete problem it solves is the cost and friction of getting business leads. Normally, pulling business listings means either paying for the Google Maps API, buying SaaS credits from services like Apify or Outscraper, or copying listings by hand. This kit asks only for a query such as "coffee shops in Austin TX" and returns a CSV — no Google Maps API key, no SaaS credits, and no data leaving the user's computer.

Key capabilities

  • Scrapes Google Maps business listings from a plain query and returns eight lead fields by default: name, phone, email, website, category, address, rating and review count.
  • Email extraction is on by default; --socials adds instagram, facebook and linkedin columns, and --full keeps all ~34 raw fields, including opening hours, coordinates, price range and reviews.
  • Geocodes a city automatically so coordinates are optional: python3 scripts/scrape.py "dentists in Denver CO" --city "Denver, CO" --depth 5.
  • Runs batch jobs across many keywords or cities in one job, either through /scrape-batch or the Python CLI's --grid flag for scraping a whole city rather than the first 120 results.
  • Ships a Claude Code skill at .claude/skills/google-maps-scraper/SKILL.md that teaches the agent the exact job API, required fields, polling, CSV cleanup and rate-limit guardrails.
  • Provides four Claude Code slash commands: /scrape, /scrape-batch, /scrape-setup and /scrape-jobs.
  • Starts the engine with one Docker command, docker compose up -d, then runs by terminal script or through an agent in plain English.

Who uses it and how

  • Freelancers and agencies building cold-outreach lists: name a business type and city, get back a CSV with phones, emails and websites ready for cold email and B2B lead generation.
  • Sales teams who want lead data to stay on their own machines rather than in a SaaS account, since no data leaves the computer.
  • Terminal-first developers and operators who run ./scripts/scrape.sh "coffee shops in Austin TX" 30.2672 -97.7431 5 directly, and use the Python CLI for batch jobs across many cities.
  • AI coding agent users who open the folder in Claude Code to auto-load the skill and four slash commands, or install it with npx skills add mahanaicoach/google-maps-scraper-kit into Codex, Cursor or another Agent Skills-compatible tool.
  • Anyone scaling a single-city job past the default result cap, using --grid 3 to scrape the whole city.

Getting started

Clone the repository (git clone https://github.com/Mahanaicoach/google-maps-scraper-kit.git), start the engine with docker compose up -d, then run a scrape with ./scripts/scrape.sh or the Python CLI. Docker Desktop is required; Python 3 is optional and uses the standard library only.

How it compares

Apify and Outscraper are paid scraping services that meter access through SaaS credits, while this kit is MIT-licensed and free to run with no Google Maps API key and no SaaS credits, keeping all data on the user's machine. The README places it against those services and against general chat AIs, framing the self-hosted Docker engine as the alternative to renting scrape capacity per job. Where the paid services sell hosted capacity, this one trades that convenience for operating the engine yourself.

When to use it — and when not to

A self-hoster must run Docker Desktop, and Python 3, though optional, uses the standard library only, so anyone unwilling to operate a local Docker engine should look elsewhere. The project scrapes Google Maps business listings only and does not scrape social platforms directly, so it is the wrong choice if the target data lives on Instagram, Facebook or LinkedIn themselves rather than the social links those listings expose. It is a young, actively maintained repository — last pushed 2026-10-13, with engine v1.18.1 verified on macOS Apple Silicon — so behaviour on untested platforms should be checked against SETUP.md before relying on it.

project readme (upstream, from github) — read inline

Google Maps Scraper Kit

GitHub stars Latest release Last commit License: MIT Runs 100% locally No API keys

Last verified working: 2026-10-14 with engine v1.18.1 on macOS Apple Silicon.

A free, open-source Google Maps scraper for lead generation that runs on your own machine. Name a business type and a city. Get back an outreach-ready CSV with name, phone, email, website, category, address, rating and review count. Add --socials for Instagram, Facebook and LinkedIn.

No Google Maps API key, no SaaS credits, no data leaving your computer. One Docker command starts the engine. Then run it from the terminal, or let Claude Code, Codex or Cursor drive it for you in plain English.

Goal Start here
Get a lead list in the next 5 minutes Quick start
Let an AI coding agent run the scrape Use it with Claude Code or any agent
Scrape many keywords or cities in one job Batch jobs
Know what you get and where it stops What you get and Honest limits
Compare it with Apify, Outscraper and chat AIs How it compares
Follow a worked recipe for dentists, roofers or restaurants Guides and recipes

Quick start

Requires Docker Desktop. Python 3 is optional and uses the standard library only.

git clone https://github.com/Mahanaicoach/google-maps-scraper-kit.git
cd google-maps-scraper-kit
docker compose up -d
./scripts/scrape.sh "coffee shops in Austin TX" 30.2672 -97.7431 5

No coordinates handy? Let the Python CLI geocode the city:

python3 scripts/scrape.py "dentists in Denver CO" --city "Denver, CO" --depth 5 --socials

Need the whole city, not just the first 120? Add --grid 3:

python3 scripts/scrape.py "dentists in Denver CO" --city "Denver, CO" --grid 3

Example output

coffee_shops_austin.csv (illustrative rows):

title phone emails website category address review_rating review_count
Example Roasters +1 512-555-0101 hello@example.com example.com Coffee shop 100 Congress Ave, Austin, TX 4.7 812
Sample Espresso Bar +1 512-555-0102 info@example.org example.org Cafe 200 S Lamar Blvd, Austin, TX 4.5 356

--socials adds instagram, facebook and linkedin columns. --full keeps all ~34 raw fields, including opening hours, coordinates, price range and reviews.

Full walkthrough, platform notes and troubleshooting: SETUP.md.

Use it with Claude Code or any agent

The kit ships a Claude Code skill that teaches the agent the exact job API, the required fields, polling, CSV cleanup and the rate-limit guardrails. It also works with Codex, Cursor and any other Agent Skills-compatible tool.

Option A: open the folder in Claude Code. The skill and four slash commands load automatically.

cd google-maps-scraper-kit
claude

Option B: install the skill into an agent you already use.

npx skills add mahanaicoach/google-maps-scraper-kit

Then ask in plain language:

Scrape gyms in Miami and give me phones, emails and websites.

The agent checks the engine is up and starts it if not, builds the job, polls in the background, downloads the CSV, keeps the 8 lead fields, and hands you a clean table plus the file.

Slash command (Claude Code) Action
/scrape in [depth] Run one scrape, return a clean table and CSV
/scrape-batch [--city "City, ST"] Run many queries as one job
/scrape-setup Start the engine and run a health check
/scrape-jobs [list | delete ] List or delete jobs

Plain requests trigger the skill too: "build me a lead list of plumbers in Phoenix". The skill scrapes Google Maps business listings only. It does not scrape social platforms directly.

What you get
8 lead fields by default name, phone, email, website, category, address, rating, review count. The engine captures ~34 raw fields; --full keeps them all.
Email extraction, on by default Visits each business website and pulls published contact emails. A second pass checks the contact and about pages of rows still missing one, then prints your found rate.
Beyond the 120 cap --grid 3 splits the city into 3 x 3 map tiles, runs them one at a time and dedupes on place_id.
Social enrichment --socials finds Instagram, Facebook and LinkedIn profiles in code (HTTP + regex). Zero AI tokens.
Auto-geocoding Type a city name. Coordinates are resolved for you via OpenStreetMap.
Batch jobs Many keywords, one job, one CSV.
Proxy rotation Built into the engine for large or repeated runs. socks5, socks5h, http, https.
Agent-native A skill plus four slash commands. The agent handles create, poll, download, clean and present.
Safe defaults API bound to 127.0.0.1, results git-ignored, rate-limit and data-law guardrails built into the skill.

Batch jobs and the Python CLI

scripts/scrape.py is a standalone, dependency-free Python CLI: single queries, batches, geocoding, socials and CSV output. It works on macOS, Linux and Windows.

python3 scripts/scrape.py --keywords-file examples/queries.example.txt --city "Denver, CO"

One keyword per line. One job. One CSV.

Honest limits

  • About 120 listings per search. Google Maps stops scrolling at roughly 120 results per search. That is Google's cap, not the kit's. --grid is the fix: it splits the city into N x N map tiles, runs one search per tile in a single batch, and dedupes the results on place_id. Tiles run one at a time, so a grid is slower and more likely to trip rate limits than a single search.
  • Emails only when a business publishes one. The extractor reads the business website, then a second pass checks its contact and about pages. Listings with no site, or a site with no visible email, return an empty emails cell. Instagram bios are not read. Expect emails on a fraction of rows, not all of them.
  • Rate limits are real. Heavy use without proxies can get your IP temporarily rate-limited by Google for minutes to hours. Your Google account is not affected. See Responsible use.
  • Apple Silicon runs the engine under amd64 emulation. It works. It is slower than native. SETUP.md has the native fallback.

How it compares

This kit Asking a chat AI Apify, Outscraper and other cloud scrapers Copying by hand
Cost Free (MIT) Free Per-result credits or subscription Free
API key or account None Account Required None
Where data goes Stays on your machine Provider's servers Provider's servers Your machine
Rows per query Whole city with --grid, deduped Close to zero Up to ~120 per keyword, unlimited keywords A handful
Emails and socials Built in No Often a paid add-on Manual
Output Clean CSV, 8 lead fields Chat text CSV or JSON Spreadsheet
Driven by an AI agent Yes, skill included n/a No No

Ask a chat AI to "scrape Google Maps" and it hits a consent wall and JavaScript-rendered pages, so you get close to zero structured rows. This kit runs a real headless scraping engine locally and gives the agent a precise operating manual for it.

Guides and recipes

One page per job, with the exact commands. Index: docs/README.md.

FAQ

Is this Google Maps scraper free? Yes. The kit is MIT licensed and the engine it runs is open source. There are no credits, subscriptions or API keys. You only need Docker on your own machine.

Do I need a Google Maps API key or the Google Places API? No. The kit drives a headless browser against Google Maps directly, so there is no API quota or billing.

How is this different from gosom/google-maps-scraper? gosom/google-maps-scraper is the scraping engine, and this kit runs its official Docker image. The kit adds the lead-focused layer on top: a one-command local setup, a dependency-free Python CLI with geocoding and batching, email and social enrichment to a clean 8-column CSV, and a Claude Code skill with slash commands and safety guardrails. See CREDITS.md.

Do I need Claude Code to use it? No. Claude Code makes it hands-free through a skill and slash commands, but scripts/scrape.py and scripts/scrape.sh run on their own from any terminal.

Does it work with Codex, Cursor or other agents? Yes. npx skills add mahanaicoach/google-maps-scraper-kit installs the skill into any Agent Skills-compatible tool. The /scrape slash commands are Claude Code only.

What data do I get for each business? Name, phone, email, website, category, address, rating and review count by default. Add --socials for Instagram, Facebook and LinkedIn, or --full for all ~34 raw fields.

How many leads can I scrape? Up to about 120 per search. Add --grid 3 to split the city into 9 map tiles and get past that cap, with duplicates removed. Batch as many keywords as you like in one job. For large or repeated runs, add proxies (see Responsible use).

Does it work on Windows, Linux and Apple Silicon Macs? Yes. Anywhere Docker runs. On Windows, use scripts/scrape.py, or run scrape.sh under WSL2 or Git Bash. SETUP.md covers the Apple Silicon note.

Is scraping Google Maps legal? It is against Google's Terms of Service, and phones and emails are personal data. Read Responsible use and follow GDPR, CCPA and CAN-SPAM. This is not legal advice.

Responsible use

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.

  • 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:
    "proxies": ["socks5://user:pass@host:port", "http://host2:port2"]
  • Treat output as leads to verify, not a dataset to resell. Phones and emails are personal data: follow GDPR, CCPA and CAN-SPAM.

For large requests, the agent flags the risk and suggests proxies, then proceeds. It refuses only clearly abusive use.

Featured in

Star history

If this kit saved you an afternoon of copy-pasting, a star helps the next person find it.

Star history chart for Mahanaicoach/google-maps-scraper-kit
Project layout
google-maps-scraper-kit/
├── docker-compose.yml      local engine on 127.0.0.1:8080
├── .env.example            config template
├── scripts/
│   ├── 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
├── CREDITS.md              scraping engine attribution and license
└── SETUP.md                full setup guide

Support

Found a bug? Open an issue with the command you ran and the error. Issues are for problems with the kit. Run your own scrapes with the quick start above; requests like "find me hotels in Hamburg" are closed without action. Contributions: CONTRIBUTING.md. Security reports: SECURITY.md.

License

Built by Mahan. MIT licensed. Third-party components: CREDITS.md.

Frequently asked questions

Is google-maps-scraper-kit free to use?

google-maps-scraper-kit is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does google-maps-scraper-kit do?

Free Google Maps scraper for lead generation. Exports phones, emails, websites and socials to CSV. Runs locally in Docker, no API keys. Claude Code skill includ

What is google-maps-scraper-kit written in?

google-maps-scraper-kit is primarily written in Python. Its source is publicly available at https://github.com/Mahanaicoach/google-maps-scraper-kit, and it has 1,432 GitHub stars.