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: guides and recipes for long-tail searches, last-verified line

Mahanaicoach656d66daa269
diff --git a/README.md b/README.md
index 24c3b52..d0f6b0a 100644
--- a/README.md
+++ b/README.md
@@ -13,6 +13,8 @@
<img alt="No API keys" src="https://img.shields.io/badge/API%20keys-none-334155?style=flat-square">
</p>
+<p align="center"><sub>Last verified working: 2026-10-14 with engine v1.18.1 on macOS Apple Silicon.</sub></p>
+
**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.
@@ -28,6 +30,7 @@ English.
| Scrape many keywords or cities in one job | [Batch jobs](#batch-jobs-and-the-python-cli) |
| Know what you get and where it stops | [What you get](#what-you-get) and [Honest limits](#honest-limits) |
| Compare it with Apify, Outscraper and chat AIs | [How it compares](#how-it-compares) |
+| Follow a worked recipe for dentists, roofers or restaurants | [Guides and recipes](docs/README.md) |
---
@@ -171,6 +174,18 @@ the agent a precise operating manual for it.
---
+## Guides and recipes
+
+One page per job, with the exact commands. Index: [docs/README.md](docs/README.md).
+
+- [Google Maps email scraper: how the kit finds business emails](docs/google-maps-email-scraper.md)
+- [Google Maps scraper in Python: every CLI flag](docs/google-maps-scraper-python.md)
+- [Google Maps scraper without an API key](docs/google-maps-scraper-no-api-key.md)
+- [Scrape Google Maps leads with Claude Code](docs/scrape-google-maps-leads-with-claude-code.md)
+- Recipes: [dentists](docs/recipes/dentist-leads.md), [roofing contractors](docs/recipes/roofing-contractor-leads.md), [restaurants](docs/recipes/restaurant-leads.md)
+
+---
+
## FAQ
**Is this Google Maps scraper free?**
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..4a48ee1
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,16 @@
+# Guides and recipes
+
+Short guides for the Google Maps Scraper Kit. Each page covers one task with the exact commands. Start with the [kit README](../README.md) for setup.
+
+## Guides
+
+- [Google Maps email scraper](google-maps-email-scraper.md): for anyone who needs contact emails and wants to know how the kit finds them.
+- [Google Maps scraper in Python](google-maps-scraper-python.md): for terminal users who want every flag of the CLI in one table.
+- [Google Maps scraper without an API key](google-maps-scraper-no-api-key.md): for anyone avoiding Places API keys, quotas and billing.
+- [Scrape Google Maps leads with Claude Code](scrape-google-maps-leads-with-claude-code.md): for people who want an AI agent to run the scrape for them.
+
+## Recipes
+
+- [Dentist leads](recipes/dentist-leads.md): for agencies and vendors selling to dental practices.
+- [Roofing contractor leads](recipes/roofing-contractor-leads.md): for anyone selling to roofers and running several search terms in one job.
+- [Restaurant leads](recipes/restaurant-leads.md): for anyone selling to restaurants, cafes and pizza places.
diff --git a/docs/google-maps-email-scraper.md b/docs/google-maps-email-scraper.md
new file mode 100644
index 0000000..842588e
--- /dev/null
+++ b/docs/google-maps-email-scraper.md
@@ -0,0 +1,60 @@
+# Google Maps email scraper: how the kit finds business emails
+
+The Google Maps Scraper Kit is a free Google Maps email scraper that runs on your own machine with no API key.
+Name a business type and a city, and you get a CSV of local businesses with their published contact emails next to phone, website and address.
+
+## How emails are found
+
+Emails are on by default. Google Maps listings carry no email field, so the kit collects them from each business website in two steps.
+
+1. The engine visits the website on every listing and pulls any email it can read there.
+2. The deep email pass then takes each row that has a website but still no email. It fetches the homepage, then up to 3 contact and about pages on the same site.
+
+The deep email pass reads `mailto:` links and plain text on those pages. It drops junk such as image file names, placeholder addresses and website-builder domains. It sorts addresses on the business's own domain first and keeps at most 3 per row. It runs in plain Python code, so it costs zero AI tokens.
+
+When the pass ends, the script prints one found-rate line. It shows how many emails came from the engine, how many the contact pages added, and the total share of rows with an email.
+
+## Run it
+
+Start the engine once, then run a search with `--city` so you can skip coordinates:
+
+```bash
+docker compose up -d
+python3 scripts/scrape.py "dentists in Denver CO" --city "Denver, CO" --depth 5
+```
+
+Skip the deep email pass for a quicker run, or skip emails entirely for the fastest run:
+
+```bash
+python3 scripts/scrape.py "dentists in Denver CO" --city "Denver, CO" --no-deep-emails
+python3 scripts/scrape.py "dentists in Denver CO" --city "Denver, CO" --no-email
+```
+
+The CSV lands in `results-<id>.csv` unless you pass `--out`.
+
+## Example output
+
+Illustrative rows only:
+
+| title | phone | emails | website | category |
+|---|---|---|---|---|
+| Example Dental Studio | +1 303-555-0101 | [email protected] | example.com | Dentist |
+| Sample Family Dentistry | +1 303-555-0102 | [email protected], [email protected] | example.org | Dentist |
+| Demo Smile Center | +1 303-555-0103 | | example.net | Dentist |
+
+The empty `emails` cell on the last row is normal. That site published no email the kit could read.
+
+## What to expect
+
+- Expect emails on a fraction of rows, not all of them. A business with no website, or a site with no visible email, returns an empty cell.
+- Instagram bios are not read. Add `--socials` to get Instagram, Facebook and LinkedIn profile links from each website instead.
+- Email extraction visits every website, so a run with emails is slower than one with `--no-email`.
+- Google Maps returns about 120 listings per search. Add `--grid 3` to split the city into 9 map tiles and get past that cap, with duplicates removed.
+- Heavy use without proxies can get your IP temporarily rate-limited by Google for minutes to hours. Run one job at a time and add proxies for large or repeated runs.
+- Scraping Google Maps is against Google's Terms of Service and emails are personal data, so read [Responsible use](../README.md#responsible-use) before you send anything.
+
+## Related
+
+- [Scrape Google Maps leads with Claude Code](scrape-google-maps-leads-with-claude-code.md)
+- [Google Maps scraper in Python](google-maps-scraper-python.md)
+- [Kit README](../README.md)
diff --git a/docs/google-maps-scraper-no-api-key.md b/docs/google-maps-scraper-no-api-key.md
new file mode 100644
index 0000000..10f5c77
--- /dev/null
+++ b/docs/google-maps-scraper-no-api-key.md
@@ -0,0 +1,56 @@
+# Google Maps scraper without an API key
+
+The Google Maps Scraper Kit is a free, local Google Maps scraper that needs no API key, no Places API and no Google Cloud account.
+It drives a headless browser against the public Google Maps site and returns a CSV of business leads, with no quota and no billing.
+
+## Why no API key is needed
+
+The kit never calls the Google Maps Platform or the Places API. So there is no key to create and no API quota or billing to manage.
+
+Instead, the engine opens Google Maps the way a browser does. The engine is gosom/google-maps-scraper, run as its official Docker image on your own machine. It searches, scrolls the result list and reads each listing. The kit then trims the output to the 8 lead fields: name, phone, email, website, category, address, rating and review count.
+
+City names are turned into coordinates by OpenStreetMap Nominatim, which is free and also needs no key.
+
+## Run it
+
+```bash
+git clone https://github.com/Mahanaicoach/google-maps-scraper-kit.git
+cd google-maps-scraper-kit
+docker compose up -d
+python3 scripts/scrape.py "plumbers in Phoenix AZ" --city "Phoenix, AZ" --depth 5
+```
+
+You need Docker Desktop. Python 3 is optional and uses the standard library only. The engine API binds to `127.0.0.1`, so it is reachable only from your machine.
+
+## Example output
+
+Illustrative rows only:
+
+| title | phone | emails | website | address | review_count |
+|---|---|---|---|---|---|
+| Example Plumbing Co | +1 602-555-0101 | [email protected] | example.com | 100 Main St, Phoenix, AZ | 214 |
+| Sample Drain Pros | +1 602-555-0102 | [email protected] | example.org | 200 Central Ave, Phoenix, AZ | 87 |
+| Demo Pipe Repair | +1 602-555-0103 | | example.net | 300 Van Buren St, Phoenix, AZ | 41 |
+
+## What no API key means for cost
+
+- No quota. There is no daily request allowance to run out of.
+- No billing. There are no credits, subscriptions or per-result charges. The kit is MIT licensed and the engine is open source.
+- No account. You do not sign in to Google or to any SaaS to run a scrape.
+- No data leaving your machine. Results are saved as local files and are git-ignored.
+
+## The trade-off
+
+Skipping the API also skips its guarantees. These are the limits you accept instead.
+
+- Google can rate-limit you. Heavy use without proxies can get your IP temporarily rate-limited for minutes to hours. Your Google account is not affected.
+- Add proxies for large or repeated runs. The engine rotates `socks5`, `socks5h`, `http` and `https` proxies for you.
+- Google Maps stops at about 120 listings per search. Add `--grid 3` to split the city into 9 map tiles, with duplicates removed.
+- Emails appear only when a business publishes one on its website.
+- Scraping Google Maps is against Google's Terms of Service, so read [Responsible use](../README.md#responsible-use) before you run large jobs.
+
+## Related
+
+- [Google Maps scraper in Python](google-maps-scraper-python.md)
+- [Scrape Google Maps leads with Claude Code](scrape-google-maps-leads-with-claude-code.md)
+- [Kit README](../README.md)
diff --git a/docs/google-maps-scraper-python.md b/docs/google-maps-scraper-python.md
new file mode 100644
index 0000000..9b37333
--- /dev/null
+++ b/docs/google-maps-scraper-python.md
@@ -0,0 +1,64 @@
+# Google Maps scraper in Python: the kit's dependency-free CLI
+
+`scripts/scrape.py` is a free Google Maps scraper Python CLI that turns a keyword and a place into a lead CSV, using only the standard library.
+It drives the engine running locally in Docker, so there is no API key, no pip install and no data leaving your machine.
+
+## Run it
+
+Start the engine, which is the gosom/google-maps-scraper official Docker image, then call the script:
+
+```bash
+docker compose up -d
+python3 scripts/scrape.py "gyms in Miami FL" 25.7617 -80.1918 --depth 5
+python3 scripts/scrape.py "cafes in Austin TX" --city "Austin, TX" --depth 5
+python3 scripts/scrape.py --keywords-file examples/queries.example.txt --city "Denver, CO"
+```
+
+On Windows, run the same commands with `py` or `python3`. Python is only the client. The engine always runs in Docker.
+
+## Every flag
+
+| Flag | What it does |
+|---|---|
+| `keyword` | The search, with the place baked in, e.g. `"coffee shops in Austin TX"`. |
+| `lat`, `lon` | Coordinates. Optional when you pass `--city`. |
+| `--city` | Geocodes a city name to coordinates via OpenStreetMap. |
+| `--depth` | How far to scroll each search. Default `5`. Higher is slower and more likely to be blocked. |
+| `--no-email` | Skips email extraction for a faster run. Emails are on by default. |
+| `--no-deep-emails` | Skips the deep email pass over contact and about pages. |
+| `--grid N` | Splits the `--city` area into N x N map tiles, one job each, deduped. Needs `--city`. Max 10. |
+| `--max-time` | Job time limit in seconds. Default `600`. |
+| `--out` | Output path. Default `results-<id>.csv`. A `.json` extension writes JSON. |
+| `--json` | Writes JSON instead of CSV. |
+| `--full` | Keeps all ~34 raw columns instead of the 8 lead fields. |
+| `--fields` | Comma-separated columns to keep, overriding the lead fields. |
+| `--socials` | Adds Instagram, Facebook and LinkedIn from each website. Slower. Zero AI tokens. |
+| `--keyword` | Adds an extra keyword to the same job. Repeatable. |
+| `--keywords-file` | Reads one keyword per line from a file. One job, one CSV. |
+
+The script creates the job, polls until it finishes, downloads the CSV and keeps the 8 lead fields. It prints a short preview and saves the full results to a file.
+
+## Example output
+
+Illustrative rows only:
+
+| title | phone | emails | website | category | review_rating |
+|---|---|---|---|---|---|
+| Example Fitness Club | +1 305-555-0101 | [email protected] | example.com | Gym | 4.6 |
+| Sample Strength Studio | +1 305-555-0102 | [email protected] | example.org | Gym | 4.8 |
+| Demo Boxing Gym | +1 305-555-0103 | | example.net | Boxing gym | 4.4 |
+
+## What to expect
+
+- Google Maps returns about 120 listings per search. Use `--grid 3` to cover a whole city past that cap.
+- Grid tiles run one at a time, so a grid is slower and more likely to trip rate limits than one search.
+- Emails appear only when a business publishes one on its website. Many rows will have an empty `emails` cell.
+- Heavy use without proxies can get your IP temporarily rate-limited by Google. Your Google account is not affected.
+- Geocoding uses the free OpenStreetMap Nominatim service, which allows about 1 request per second.
+- Scraping Google Maps is against Google's Terms of Service, so read [Responsible use](../README.md#responsible-use) first.
+
+## Related
+
+- [Google Maps email scraper](google-maps-email-scraper.md)
+- [Google Maps scraper without an API key](google-maps-scraper-no-api-key.md)
+- [Kit README](../README.md)
diff --git a/docs/recipes/dentist-leads.md b/docs/recipes/dentist-leads.md
new file mode 100644
index 0000000..2dda76e
--- /dev/null
+++ b/docs/recipes/dentist-leads.md
@@ -0,0 +1,72 @@
+# Scrape dentists from Google Maps: a lead list recipe
+
+This recipe shows how to scrape dentists from Google Maps for one city with the Google Maps Scraper Kit, from a quick test to the whole city.
+You get a CSV of dental practices with phone, email, website, address, rating and review count, free and local, with no API key.
+
+## Step 1: Run one search
+
+Start the engine, then test with one search at the default depth:
+
+```bash
+docker compose up -d
+python3 scripts/scrape.py "dentists in Denver CO" --city "Denver, CO" --depth 5
+```
+
+Check the preview and the found-rate line for emails. If the rows look right, widen the run.
+
+## Step 2: Cover the whole city
+
+One search stops at about 120 listings. Split the city into a 3 x 3 grid of map tiles:
+
+```bash
+python3 scripts/scrape.py "dentists in Denver CO" --city "Denver, CO" --grid 3
+```
+
+That is 9 jobs, run one at a time. Results are deduped on `place_id`, and rows outside the city box are dropped.
+
+## Step 3: Add social profiles
+
+Add `--socials` for Instagram, Facebook and LinkedIn links found on each practice website:
+
+```bash
+python3 scripts/scrape.py "dentists in Denver CO" --city "Denver, CO" --grid 3 --socials
+```
+
+Want specialists too? The kit ships a ready batch file with dentists, orthodontists, dental hygienists and pediatric dentists in Denver:
+
+```bash
+python3 scripts/scrape.py --keywords-file examples/queries.example.txt --city "Denver, CO"
+```
+
+## Example output
+
+Illustrative rows only:
+
+| title | phone | emails | website | review_rating | review_count | instagram |
+|---|---|---|---|---|---|---|
+| Example Dental Studio | +1 303-555-0101 | [email protected] | example.com | 4.9 | 312 | instagram.com/exampledental |
+| Sample Family Dentistry | +1 303-555-0102 | [email protected] | example.org | 4.6 | 128 | |
+| Demo Orthodontics | +1 303-555-0103 | | example.net | 4.8 | 64 | instagram.com/demoortho |
+
+## Columns that matter for dental outreach
+
+- `title` and `phone`: who to call, and the number to call.
+- `emails`: the published practice inbox. The deep email pass checks contact and about pages to fill it.
+- `website`: the site you will review before you reach out.
+- `category`: separates general dentists from orthodontists and other specialists.
+- `review_rating` and `review_count`: a quick read on how established the practice is.
+- `instagram`, `facebook`, `linkedin`: added by `--socials` when the site links them.
+
+## What to expect
+
+- Emails appear only when a practice publishes one on its website. Expect some empty cells.
+- A grid is slower than one search and more likely to trip rate limits. Run one job at a time.
+- Add proxies for large or repeated runs. Heavy use without them can get your IP temporarily rate-limited.
+- Socials appear only when the practice links them on its own site.
+- Phones and emails are personal data, so read [Responsible use](../../README.md#responsible-use) before outreach.
+
+## Related
+
+- [Roofing contractor leads recipe](roofing-contractor-leads.md)
+- [Google Maps email scraper](../google-maps-email-scraper.md)
+- [Kit README](../../README.md)
diff --git a/docs/recipes/restaurant-leads.md b/docs/recipes/restaurant-leads.md
new file mode 100644
index 0000000..275d833
--- /dev/null
+++ b/docs/recipes/restaurant-leads.md
@@ -0,0 +1,73 @@
+# Scrape restaurants from Google Maps: a lead list recipe
+
+This recipe shows how to scrape restaurants from Google Maps for one city with the Google Maps Scraper Kit, including cafes and pizza places in the same run.
+You get a CSV of food businesses with phone, email, website, address, rating and review count, free and local, with no API key.
+
+## Step 1: Run one search
+
+Start the engine, then test with one search at the default depth:
+
+```bash
+docker compose up -d
+python3 scripts/scrape.py "restaurants in Austin TX" --city "Austin, TX" --depth 5
+```
+
+Check the preview and the email found-rate line before you scale up.
+
+## Step 2: Cover the food categories you sell to
+
+Food businesses sit in many Google Maps categories. A search for restaurants may miss cafes and pizza places. Add each term with `--keyword` to run them as one job and one CSV:
+
+```bash
+python3 scripts/scrape.py "restaurants in Austin TX" --keyword "cafes in Austin TX" \
+ --keyword "pizza in Austin TX" --city "Austin, TX"
+```
+
+For a whole city past the ~120 per search cap, add `--grid 3`. It splits the city into 9 map tiles, runs them one at a time and dedupes on `place_id`.
+
+## Step 3: Add hours and price range for qualification
+
+`--full` keeps all ~34 raw columns, including `open_hours` and `price_range`:
+
+```bash
+python3 scripts/scrape.py "restaurants in Austin TX" --city "Austin, TX" --full
+```
+
+To keep the file lean, pick your own columns with `--fields`:
+
+```bash
+python3 scripts/scrape.py "restaurants in Austin TX" --city "Austin, TX" \
+ --fields "title,phone,emails,website,category,open_hours,price_range,review_count"
+```
+
+## Example output
+
+Illustrative rows only:
+
+| title | phone | emails | category | price_range | review_count |
+|---|---|---|---|---|---|
+| Example Kitchen | +1 512-555-0101 | [email protected] | Restaurant | $$ | 640 |
+| Sample Slice | +1 512-555-0102 | [email protected] | Pizza restaurant | $ | 215 |
+| Demo Coffee House | +1 512-555-0103 | | Cafe | $ | 98 |
+
+## Columns that matter for restaurant outreach
+
+- `category`: splits restaurants, cafes and pizza places so you can tailor each message.
+- `price_range`: a quick read on the kind of venue. Needs `--full` or `--fields`.
+- `open_hours`: shows when the venue is open, so you can time a call. Needs `--full` or `--fields`.
+- `review_count` and `review_rating`: a signal of traffic and reputation.
+- `phone`, `emails` and `website`: the contact channels.
+
+## What to expect
+
+- Emails appear only when a business publishes one on its website. Many venues will have an empty cell.
+- Not every listing has a price range or opening hours, so those cells can be empty too.
+- A grid or many keywords is a large job. Run one job at a time and add proxies for repeated runs.
+- Heavy use without proxies can get your IP temporarily rate-limited by Google for minutes to hours.
+- Phones and emails are personal data, so read [Responsible use](../../README.md#responsible-use) before outreach.
+
+## Related
+
+- [Roofing contractor leads recipe](roofing-contractor-leads.md)
+- [Google Maps scraper in Python](../google-maps-scraper-python.md)
+- [Kit README](../../README.md)
diff --git a/docs/recipes/roofing-contractor-leads.md b/docs/recipes/roofing-contractor-leads.md
new file mode 100644
index 0000000..d6a19d9
--- /dev/null
+++ b/docs/recipes/roofing-contractor-leads.md
@@ -0,0 +1,76 @@
+# Scrape roofing contractors from Google Maps: a lead list recipe
+
+This recipe shows how to scrape roofing contractors from Google Maps for one city with the Google Maps Scraper Kit, using one batch job for several search terms.
+You get a CSV of roofers with phone, email, website, address, rating and review count, free and local, with no API key.
+
+## Step 1: Run one search
+
+Start the engine, then test with one search at the default depth:
+
+```bash
+docker compose up -d
+python3 scripts/scrape.py "roofing contractors in Phoenix AZ" --city "Phoenix, AZ" --depth 5
+```
+
+Check the preview and the email found-rate line before you scale up.
+
+## Step 2: Batch the roofing variants
+
+Roofers list themselves under different names on Google Maps. Put each variant on its own line in a keywords file. Blank lines and lines starting with `#` are ignored.
+
+`roofing.txt`:
+
+```text
+# One keyword per line. All lines run as one job and one CSV.
+roofing contractor in Phoenix AZ
+roof repair in Phoenix AZ
+roofers in Phoenix AZ
+```
+
+Run them as one job:
+
+```bash
+python3 scripts/scrape.py --keywords-file roofing.txt --city "Phoenix, AZ"
+```
+
+## Step 3: Cover the whole city
+
+Each search stops at about 120 listings. Add `--grid 3` to split the city into 9 map tiles, run one at a time, with duplicates removed on `place_id`:
+
+```bash
+python3 scripts/scrape.py --keywords-file roofing.txt --city "Phoenix, AZ" --grid 3
+```
+
+Add `--socials` to any of these commands for Instagram, Facebook and LinkedIn links found on each website.
+
+## Example output
+
+Illustrative rows only:
+
+| title | phone | emails | website | category | review_count |
+|---|---|---|---|---|---|
+| Example Roofing Co | +1 602-555-0101 | [email protected] | example.com | Roofing contractor | 245 |
+| Sample Roof Repair | +1 602-555-0102 | [email protected] | example.org | Roofing contractor | 58 |
+| Demo Roofers | +1 602-555-0103 | | example.net | Roofer | 19 |
+
+## Columns that matter for roofing outreach
+
+- `phone`: the main contact channel for most trade businesses.
+- `emails`: filled when the roofer publishes one. The deep email pass checks contact and about pages.
+- `website`: an empty cell here also means no email or socials could be found.
+- `category`: shows how each business describes itself.
+- `review_rating` and `review_count`: a quick read on size and reputation.
+
+## What to expect
+
+- Overlapping terms can return the same business twice. The script dedupes on `place_id` only in `--grid` runs, so check a plain batch CSV for repeats.
+- Emails appear only when a business publishes one on its website.
+- A grid with three keywords is a large job. The script prints a rate-limit warning and proceeds.
+- Add proxies for large or repeated runs. Heavy use without them can get your IP temporarily rate-limited.
+- Phones and emails are personal data, so read [Responsible use](../../README.md#responsible-use) before outreach.
+
+## Related
+
+- [Dentist leads recipe](dentist-leads.md)
+- [Restaurant leads recipe](restaurant-leads.md)
+- [Kit README](../../README.md)
diff --git a/docs/scrape-google-maps-leads-with-claude-code.md b/docs/scrape-google-maps-leads-with-claude-code.md
new file mode 100644
index 0000000..694b045
--- /dev/null
+++ b/docs/scrape-google-maps-leads-with-claude-code.md
@@ -0,0 +1,73 @@
+# Scrape Google Maps leads with Claude Code
+
+The Google Maps Scraper Kit lets you scrape Google Maps leads with Claude Code by asking in plain English, and get back a clean table plus a CSV.
+It is free and runs locally: the agent drives a scraping engine in Docker on your machine, with no API key and no SaaS credits.
+
+## Set it up
+
+Install Docker Desktop, then pick one option.
+
+Option A: open the kit folder in Claude Code. The skill and four slash commands load automatically.
+
+```bash
+git clone https://github.com/Mahanaicoach/google-maps-scraper-kit.git
+cd google-maps-scraper-kit
+claude
+```
+
+Option B: install the skill into an agent you already use.
+
+```bash
+npx skills add mahanaicoach/google-maps-scraper-kit
+```
+
+The skill works with Claude Code, Codex, Cursor and any other Agent Skills-compatible tool. The slash commands are Claude Code only.
+
+## Ask in plain language
+
+> Scrape gyms in Miami and give me phones, emails and websites.
+
+Or use a slash command in Claude Code:
+
+| Slash command | Action |
+|---|---|
+| `/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 |
+
+## What the agent does
+
+1. Runs a health check on the engine at `localhost:8080`, and starts it with `docker compose up -d` if it is down.
+2. Asks once whether you also want Instagram, Facebook and LinkedIn profiles.
+3. Builds the job with the required `max_time`, `lat` and `lon`, with emails on by default.
+4. Polls the job in the background until it finishes.
+5. Downloads the CSV.
+6. Keeps the 8 lead fields: name, phone, email, website, category, address, rating and review count.
+7. Saves the file, then presents a short table and the CSV path instead of dumping every row into chat.
+
+The kit's local commands and `localhost` calls are pre-approved in `.claude/settings.json`, so Claude Code does not prompt for each one.
+
+## Example output
+
+Illustrative rows only:
+
+| title | phone | emails | website | category |
+|---|---|---|---|---|
+| Example Fitness Club | +1 305-555-0101 | [email protected] | example.com | Gym |
+| Sample Strength Studio | +1 305-555-0102 | [email protected] | example.org | Gym |
+| Demo Boxing Gym | +1 305-555-0103 | | example.net | Boxing gym |
+
+## What to expect
+
+- Google Maps returns about 120 listings per search. Ask for the whole city and the agent runs `--grid 3`, which splits it into 9 tiles and dedupes the results.
+- Emails come back only when a business publishes one on its website. Expect some empty cells.
+- For large jobs, the agent prints one short warning about temporary IP rate limits and suggests proxies, then proceeds.
+- The skill scrapes Google Maps business listings only. It does not scrape social platforms directly.
+- Scraping Google Maps is against Google's Terms of Service, so read [Responsible use](../README.md#responsible-use) before outreach.
+
+## Related
+
+- [Google Maps email scraper](google-maps-email-scraper.md)
+- [Dentist leads recipe](recipes/dentist-leads.md)
+- [Kit README](../README.md)