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: correct the field count, the arm64 note and the legal section

Won Ecosystemf786210e4bee
diff --git a/.claude/skills/google-maps-scraper/SKILL.md b/.claude/skills/google-maps-scraper/SKILL.md
index 05891da..7af18a6 100644
--- a/.claude/skills/google-maps-scraper/SKILL.md
+++ b/.claude/skills/google-maps-scraper/SKILL.md
@@ -1,6 +1,6 @@
---
name: google-maps-scraper
-description: Google Maps scraper for lead generation. Turns a business type and a place into a clean CSV of local businesses by driving the gosom/google-maps-scraper engine, running locally in Docker as a REST API on localhost:8080. Returns 8 lead fields by default (name, phone, email, website, category, address, rating and review count), plus optional Instagram, Facebook and LinkedIn profiles or all ~34 raw fields. Use when the user wants a lead list, "a list of [businesses] in [place]", local business data, contact enrichment for places (emails, phones, socials), or a whole-city run past Google's ~120 results per search. Do not use for scraping Instagram, TikTok, YouTube, X or any other social media platform directly.
+description: Google Maps scraper for lead generation. Turns a business type and a place into a clean CSV of local businesses by driving the gosom/google-maps-scraper engine, running locally in Docker as a REST API on localhost:8080. Returns 8 lead fields by default (name, phone, email, website, category, address, rating and review count), plus optional Instagram, Facebook and LinkedIn profiles or all 36 raw fields. Use when the user wants a lead list, "a list of [businesses] in [place]", local business data, contact enrichment for places (emails, phones, socials), or a whole-city run past Google's ~120 results per search. Do not use for scraping Instagram, TikTok, YouTube, X or any other social media platform directly.
---
# Google Maps Scraper
@@ -11,7 +11,7 @@ Turn a business type and a location into clean lead rows by driving the local en
The engine (gosom/google-maps-scraper) runs as a local Docker container with a REST API at
`http://localhost:8080`. It has no auth, so it stays bound to localhost. A scrape is an **async job**:
create it, poll until it is done, then download a CSV. One job can run many keywords. Each result has
-up to **34 raw fields**.
+up to **36 raw fields**.
## Step 0: Check the engine is running
```bash
@@ -71,13 +71,14 @@ done
```bash
curl -s "http://localhost:8080/api/v1/jobs/$ID/download" -o results.csv
```
-CSV columns (34): `input_id, link, title, category, address, open_hours, popular_times, website, phone,
+CSV columns (36): `input_id, link, title, category, address, open_hours, popular_times, website, phone,
plus_code, review_count, review_rating, reviews_per_rating, latitude, longitude, cid, status,
-descriptions, reviews_link, thumbnail, timezone, price_range, data_id, place_id, images, reservations,
-order_online, menu, owner, complete_address, about, user_reviews, user_reviews_extended, emails`.
+descriptions, reviews_link, thumbnail, timezone, price_range, data_id, street_view_url, place_id,
+images, reservations, order_online, menu, owner, complete_address, credit_cards_accepted, about,
+user_reviews, user_reviews_extended, emails`. Multiple emails arrive in one cell, joined by `, `.
### Return only the 8 lead fields (default)
-The raw CSV has 34 columns and most are noise for outreach. **By default, return only the 8 lead
+The raw CSV has 36 columns and most are noise for outreach. **By default, return only the 8 lead
fields**, the data used to contact and qualify a lead, and **drop everything else**:
> `title` (name), `phone`, `emails`, `website`, `category`, `address`, `review_rating`, `review_count`
@@ -91,7 +92,7 @@ outreach), `link`, `plus_code`, `cid`, `data_id`, `place_id`, `open_hours`, `pop
`scripts/scrape.py` already returns exactly the 8 lead fields. Use `--full` to keep all columns, or
`--fields "a,b,c"` to choose your own. It **saves a CSV file by default** (`results-<id>.csv`); pass
`--json` for JSON. If you call the API directly, **strip to the lead fields yourself** before
-presenting. Never dump the full 34-column row at the user.
+presenting. Never dump the full 36-column row at the user.
### Social profiles: always ask the user (Instagram, Facebook, LinkedIn)
Google Maps has no social links, so socials are an enrichment step: visit each business `website` and
diff --git a/README.md b/README.md
index d0f6b0a..993f122 100644
--- a/README.md
+++ b/README.md
@@ -67,7 +67,7 @@ python3 scripts/scrape.py "dentists in Denver CO" --city "Denver, CO" --grid 3
| Example Roasters | +1 512-555-0101 | [email protected] | example.com | Coffee shop | 100 Congress Ave, Austin, TX | 4.7 | 812 |
| Sample Espresso Bar | +1 512-555-0102 | [email protected] | 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,
+`--socials` adds `instagram`, `facebook` and `linkedin` columns. `--full` keeps all 36 raw fields,
including opening hours, coordinates, price range and reviews.
Full walkthrough, platform notes and troubleshooting: [SETUP.md](SETUP.md).
@@ -116,7 +116,7 @@ scrapes Google Maps business listings only. It does not scrape social platforms
| | |
|---|---|
-| **8 lead fields by default** | name, phone, email, website, category, address, rating, review count. The engine captures ~34 raw fields; `--full` keeps them all. |
+| **8 lead fields by default** | name, phone, email, website, category, address, rating, review count. The engine captures 36 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. |
@@ -151,8 +151,8 @@ One keyword per line. One job. One CSV.
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](#responsible-use).
-- **Apple Silicon runs the engine under amd64 emulation.** It works. It is slower than native.
- [SETUP.md](SETUP.md) has the native fallback.
+- **Apple Silicon runs natively from v1.18.0 on.** The image publishes arm64 builds, so M-series
+ Macs need no emulation. Older tags are amd64 only and run under emulation.
---
@@ -212,7 +212,7 @@ 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.
+for Instagram, Facebook and LinkedIn, or `--full` for all 36 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,
@@ -225,7 +225,8 @@ Bash. [SETUP.md](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](#responsible-use) and follow GDPR, CCPA and CAN-SPAM. This is not legal advice.
+[Responsible use](#responsible-use) and follow the law where the data is used: GDPR and CCPA
+abroad, and LGPD in Brazil. This is not legal advice.
---
@@ -241,7 +242,8 @@ your IP **temporarily rate-limited** (minutes to hours). Your Google account is
"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.
+ follow GDPR, CCPA, CAN-SPAM and, in Brazil, LGPD — including the lawful basis, the purpose and an
+ opt-out before any outreach.
For large requests, the agent flags the risk and suggests proxies, then proceeds. It refuses only
clearly abusive use.
diff --git a/SETUP.md b/SETUP.md
index 4b15b16..4d011d9 100644
--- a/SETUP.md
+++ b/SETUP.md
@@ -22,8 +22,8 @@ docker ps # should NOT error (means the daemon is up)
```
> **Platform notes:**
-> - **Apple Silicon (M1/M2/M3):** the engine image is `linux/amd64` and runs under emulation. If the
-> container won't start, uncomment the `platform: linux/amd64` line in `docker-compose.yml`.
+> - **Apple Silicon (M1/M2/M3):** from v1.18.0 the image publishes an arm64 build, so it runs
+> natively and no `platform` line is needed. Only older tags are amd64 and run under emulation.
> - **Windows:** use `scripts/scrape.py` (run with `py` or `python3`). The bash script `scrape.sh` needs
> **WSL2** or **Git Bash**.
@@ -68,7 +68,7 @@ If `curl` returns a JSON array, the engine is live.
> temporarily rate-limited by Google, for minutes to hours. Your Google account is not affected. Run
> one job at a time, start at `depth 5`, and add proxies for large or repeated runs. Scraping Google
> Maps is against Google's Terms of Service, and phones and emails are personal data, so follow GDPR,
-> CCPA and CAN-SPAM. Details: [Responsible use](README.md#responsible-use).
+> CCPA and CAN-SPAM — and LGPD if you operate in Brazil. Details: [Responsible use](README.md#responsible-use).
---
diff --git a/docker-compose.yml b/docker-compose.yml
index 2c8b39b..76a8a38 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -10,8 +10,8 @@ services:
# Bumped from v1.15.0 on 2026-09-23: that build's embedded Playwright driver (1.57.0)
# returns 404 from Microsoft's CDN, which purges old driver builds. v1.18.1 ships a driver
# version that is still hosted.
- # The published image is linux/amd64. On Apple Silicon (M1/M2/M3) it runs under emulation.
- # If the container won't start there, uncomment the 'platform' line below. Default: commented out.
+ # v1.18.1 publishes both amd64 and arm64, so Apple Silicon (M1/M2/M3) runs it natively.
+ # Only older tags are amd64 and need the 'platform' line below. Default: commented out.
image: gosom/google-maps-scraper:v1.18.1
# platform: linux/amd64
container_name: gmaps-scraper
diff --git a/docs/google-maps-scraper-python.md b/docs/google-maps-scraper-python.md
index 9b37333..d86443e 100644
--- a/docs/google-maps-scraper-python.md
+++ b/docs/google-maps-scraper-python.md
@@ -30,7 +30,7 @@ On Windows, run the same commands with `py` or `python3`. Python is only the cli
| `--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. |
+| `--full` | Keeps all 36 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. |