Skip to content
Back to search

google-maps-scraper-kit

Local Google Maps lead extraction, operated by Claude. Clean CSVs with phones, emails, websites and socials. No API keys, runs on your machine.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Mahanaicoach/google-maps-scraper-kit with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Mahanaicoach/google-maps-scraper-kit'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mahanaicoach--google-maps-scraper-kit/badge.svg)](/listings/mahanaicoach--google-maps-scraper-kit)

HTML

<a href="/listings/mahanaicoach--google-maps-scraper-kit"><img src="/api/listings/mahanaicoach--google-maps-scraper-kit/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requires [Docker Desktop](https://www.docker.com/products/docker-desktop). Python 3 is optional (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

Or open the folder in Claude Code and say:

> Scrape gyms in Miami and give me phones and websites.

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 |

Add `--socials` for `instagram`, `facebook` and `linkedin` columns, or `--full` for all ~34 raw fields.

Detailed setup: [SETUP.md](SETUP.md). Skill reference: [SKILL.md](.claude/skills/google-maps-scraper/SKILL.md).

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 529 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Google Maps Scraper Kit
  2. <p align="center">
  3. <img src="assets/banner.svg" alt="Google Maps Scraper Kit: free local Google Maps scraper for lead generation, driven by Claude Code" width="100%">
  4. </p>
  5. <p align="center">
  6. <a href="https://github.com/Mahanaicoach/google-maps-scraper-kit/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/Mahanaicoach/google-maps-scraper-kit?style=flat-square&color=f59e0b"></a>
  7. <a href="https://github.com/Mahanaicoach/google-maps-scraper-kit/releases"><img alt="Latest release" src="https://img.shields.io/github/v/release/Mahanaicoach/google-maps-scraper-kit?style=flat-square&color=0b1220"></a>
  8. <a href="https://github.com/Mahanaicoach/google-maps-scraper-kit/commits/master"><img alt="Last commit" src="https://img.shields.io/github/last-commit/Mahanaicoach/google-maps-scraper-kit?style=flat-square&color=334155"></a>
  9. <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-0b1220?style=flat-square"></a>
  10. <img alt="Runs 100% locally" src="https://img.shields.io/badge/runs-100%25%20local-059669?style=flat-square">
  11. <img alt="No API keys" src="https://img.shields.io/badge/API%20keys-none-334155?style=flat-square">
  12. <img alt="Python 3.9+" src="https://img.shields.io/badge/python-3.9%2B-3776ab?style=flat-square&logo=python&logoColor=white">
  13. <img alt="macOS, Windows, Linux" src="https://img.shields.io/badge/macOS%20%7C%20Windows%20%7C%20Linux-supported-475569?style=flat-square">
  14. <a href="#use-it-with-claude-code-or-any-agent"><img alt="Claude Code skill" src="https://img.shields.io/badge/Claude%20Code-skill-d97757?style=flat-square"></a>
  15. </p>
  16. <p align="center">
  17. <a href="#quick-start"><b>Quick start</b></a> ·
  18. <a href="#use-it-with-claude-code-or-any-agent"><b>Use with an AI agent</b></a> ·
  19. <a href="#what-you-get"><b>Features</b></a> ·
  20. <a href="#how-it-compares"><b>Compare</b></a> ·
  21. <a href="docs/README.md"><b>Recipes</b></a> ·
  22. <a href="#faq"><b>FAQ</b></a>
  23. </p>
  24. <p align="center"><sub>Last verified working: 2026-11-01, fresh install of v2.1.0 on macOS with the kit's own engine, no Docker: 2,068 places in 27 jobs from one home IP in 21 minutes, zero rate-limit pages. Also runs on Linux (amd64 and arm64), Windows and Docker.</sub></p>
  25. **A free, open-source Google Maps scraper for lead generation that runs on your own machine.**
  26. Name a business type and a city. Get back an outreach-ready CSV with name, phone, email, website,
  27. category, address, rating and review count, plus Instagram, Facebook, LinkedIn, TikTok, YouTube and X
  28. links when the site shows them. Add `--no-socials` to skip those, or `--no-website` for the businesses
  29. that still need a site.
  30. No Google Maps API key, no SaaS credits, no data leaving your computer. One command starts the
  31. engine, with or without Docker. Then run it from the terminal, or let Claude Code, Codex or Cursor
  32. drive it for you in plain English.
  33. <table>
  34. <tr>
  35. <td align="center" width="25%">⚡<br><b>100 leads + emails</b><br><sub>in 44 seconds, measured</sub></td>
  36. <td align="center" width="25%">📧<br><b>Emails + 6 socials</b><br><sub>on by default, zero AI tokens</sub></td>
  37. <td align="center" width="25%">🗺️<br><b>Past Google's 120 cap</b><br><sub><code>--grid</code> and <code>--deep-scan</code></sub></td>
  38. <td align="center" width="25%">🔒<br><b>100% local</b><br><sub>no API key, no credits, no Docker</sub></td>
  39. </tr>
  40. </table>
  41. | Goal | Start here |
  42. |---|---|
  43. | 🚀 Get a lead list in the next 5 minutes | [Quick start](#quick-start) |
  44. | 🤖 Let an AI coding agent run the scrape | [Use it with Claude Code or any agent](#use-it-with-claude-code-or-any-agent) |
  45. | 📦 Scrape many keywords or cities in one job | [Batch jobs](#batch-jobs-and-the-python-cli) |
  46. | 📋 Know what you get and where it stops | [What you get](#what-you-get) and [Honest limits](#honest-limits) |
  47. | 🏆 Compare it with gosom, omkarcloud, Apify, Outscraper and chat AIs | [How it compares](#how-it-compares) and [the open-source comparison](docs/best-google-maps-scrapers.md) |
  48. | 🧑‍🍳 Follow a worked recipe for dentists, roofers or restaurants | [Guides and recipes](docs/README.md) |
  49. <sub>Sponsored by [Swiftproxy](https://www.swiftproxy.net/?ref=googlemapsscraperkit) and [SerpApi](https://serpapi.com/maps-scraper-kit-github). Paid placements; details [below](#sponsored-by).</sub>
  50. ---
  51. ## Quick start
  52. Requires Python 3.9 or newer and Google Chrome (or Chromium, Edge or Brave). The engine and the
  53. scripts use the Python standard library by default. Optional website rendering adds Playwright
  54. ([setup](SETUP.md#optional-website-rendering-playwright)); the basic crawl needs no pip install. No browser
  55. installed? The first start downloads Chrome for Testing once, about 100 MB, checked against a pinned
  56. SHA-256.
  57. Open a terminal (macOS: Terminal; Windows: PowerShell) and run these four lines:
  58. ```bash
  59. git clone https://github.com/Mahanaicoach/google-maps-scraper-kit.git
  60. cd google-maps-scraper-kit
  61. python3 scripts/engine.py start
  62. python3 scripts/scrape.py "coffee shops in Austin TX" 30.2672 -97.7431 --depth 2
  63. ```
  64. **Port 8080 taken?** Run `cp .env.example .env`, set `SCRAPER_PORT=8081` (any free port) in it, and start again.
  65. Then use that port wherever these docs say 8080.
  66. On Windows, type `py` in place of `python3`. Stop the engine with `python3 scripts/engine.py stop`.
  67. **Prefer Docker?** Replace the third line with `docker compose up -d`, with
  68. [Docker Desktop](https://www.docker.com/products/docker-desktop) installed and open. If the native
  69. engine is running, stop it first (`python3 scripts/engine.py stop`). The two keep separate job lists,
  70. so jobs started in one do not show in the other. The first run builds the engine image, about a
  71. minute. It is the same engine on the same port, so every other command stays the same.
  72. Prefer clicking? http://localhost:8080 has a form; each job gives a Leads CSV (the 8 lead fields and
  73. socials, junk emails dropped), the full raw CSV or JSON.
  74. Already running another copy of the kit on this machine? Set `SCRAPER_PORT` in `.env` first
  75. (SETUP §6, "second copy").
  76. No coordinates handy? Let the Python CLI geocode the city:
  77. ```bash
  78. python3 scripts/scrape.py "dentists in Denver CO" --city "Denver, CO" --depth 5
  79. ```
  80. Each `--depth` step loads one more batch of about 20 places: `--depth 2` returns about 40, `--depth 5`
  81. up to about 100, near Google's cap of about 120 per search. Need the whole city? Add `--grid 3`:
  82. ```bash
  83. python3 scripts/scrape.py "dentists in Denver CO" --city "Denver, CO" --grid 3
  84. ```
  85. Want every listing, not just a grid's worth? `--deep-scan` (the `!` option: slower) runs the grid, then
  86. splits every tile that came back at Google's cap into four sub-tiles one zoom level in, deduped:
  87. ```bash
  88. python3 scripts/scrape.py "restaurants in Denver CO" --city "Denver, CO" --deep-scan
  89. ```
  90. ### Example output
  91. `results-<short job id>.csv` from the first command above (pass `--out` to name it yourself).
  92. Illustrative rows. The file also has six social columns after these eight (see below):
  93. | title | phone | emails | website | category | address | review_rating | review_count |
  94. |---|---|---|---|---|---|---|---|
  95. | Example Roasters | +1 512-555-0101 | hello@example.com | example.com | Coffee shop | 100 Congress Ave, Austin, TX | 4.7 | 312 |
  96. | Sample Espresso Bar | +1 512-555-0102 | info@example.org | example.org | Cafe | 200 S Lamar Blvd, Austin, TX | 4.5 | 128 |
  97. `review_count` works in headless mode; see [Honest limits](#honest-limits).
  98. `--browser-sites` enables optional Playwright retries when HTTP finds no emails or social profile
  99. links. It renders JavaScript and shares the rendered homepage between both passes. Output adds
  100. `website_fetch_status`: `http`, `rendered`, `blocked`, `timeout`, `budget_exhausted` or `error`.
  101. See [optional setup](SETUP.md#optional-website-rendering-playwright).
  102. The social columns `instagram`, `facebook`, `linkedin`, `tiktok`, `youtube` and `x` come after the eight
  103. lead fields by default. `--no-socials` drops them. `--tech` adds
  104. `fb_pixel`, `google_ads_tag`, `analytics`, `bing_ads`, `linkedin_insight`, `tiktok_pixel`, `cms`,
  105. `mobile_friendly` and `intent_score`, and sorts the hottest leads first. `--verify-emails` adds
  106. `email_host`. `--full` keeps every raw column, including coordinates, place IDs, all categories, the
  107. week's opening hours and whether the place is open now.
  108. Full walkthrough, platform notes and troubleshooting: [SETUP.md](SETUP.md).
  109. ---
  110. ## Sponsored by
  111. ### [Swiftproxy](https://www.swiftproxy.net/?ref=googlemapsscraperkit) - Residential proxies for Google Maps scraping
  112. <a href="https://www.swiftproxy.net/?ref=googlemapsscraperkit"><img src="assets/sponsors/swiftproxy.webp" alt="Swiftproxy: outreach-ready residential IPs for Google Maps lead generation" width="600"></a>
  113. 90M+ residential IPs across 220+ locations, rotating or static, over HTTP(S) and SOCKS5, so big
  114. Google Maps and multi-city jobs keep running. Use code `PROXY90` for 10% off.
  115. [**Try Swiftproxy →**](https://www.swiftproxy.net/?ref=googlemapsscraperkit)
  116. ---
  117. ### [SerpApi](https://serpapi.com/maps-scraper-kit-github) - Google Maps API in JSON and Markdown
  118. <a href="https://serpapi.com/maps-scraper-kit-github"><img src="assets/sponsors/serpapi.png" alt="SerpApi: complete Maps API, available in JSON and Markdown" width="600"></a>
  119. Access Google Maps listings, reviews, directions, and other public search data with SerpApi's Google
  120. Maps API, delivered as clean, structured JSON and Markdown.
  121. [**Try SerpApi →**](https://serpapi.com/maps-scraper-kit-github)
  122. <p align="center"><sub><a href="https://github.com/sponsors/Mahanaicoach">Become a sponsor</a> · Sponsors also appear in the sponsor box of every installed copy's web UI, read from <a href="assets/sponsors/sponsors.json">assets/sponsors/sponsors.json</a>.</sub></p>
  123. ---
  124. ## Use it with Claude Code or any agent
  125. The kit ships a [Claude Code skill](.claude/skills/google-maps-scraper/SKILL.md) that teaches the
  126. agent to run `scripts/scrape.py` for every scrape, what the output holds, and the rate-limit and
  127. data-handling guardrails.
  128. It also works with Codex, Cursor and any other [Agent Skills](https://agentskills.io)-compatible tool.
  129. **Option A: open the folder in Claude Code.** The skill and four slash commands load automatically.
  130. ```bash
  131. cd google-maps-scraper-kit
  132. claude
  133. ```
  134. **Option B: install the skill into an agent you already use.**
  135. ```bash
  136. npx skills add mahanaicoach/google-maps-scraper-kit
  137. ```
  138. This installs the skill file only. The engine and `scripts/scrape.py` ship with the kit, so the
  139. agent first asks you to install it (the [Quick start](#quick-start)) and then works from its folder.
  140. The slash commands come with Option A.
  141. Then ask in plain language:
  142. > Scrape gyms in Miami and give me phones, emails and websites.
  143. The agent checks the engine is up and starts it if not, runs `scripts/scrape.py` in the background
  144. (it creates, waits for and saves the job), and hands you a clean table of the 8 lead fields plus the file.
  145. | Slash command (Claude Code) | Action |
  146. |---|---|
  147. | `/scrape <business> in <city, ST> [depth]` | Run one scrape, return a clean table and CSV |
  148. | `/scrape-batch <keywords-file> [--city "City, ST"]` | Run many queries as one job |
  149. | `/scrape-setup` | Start the engine and run a health check |
  150. | `/scrape-jobs [list \| delete <id>]` | List or delete jobs |
  151. Plain requests trigger the skill too: *"build me a lead list of plumbers in Phoenix"*. The skill
  152. scrapes Google Maps business listings only. It does not scrape social platforms directly.
  153. ---
  154. ## What you get
  155. | | |
  156. |---|---|
  157. | 📇 **8 lead fields by default** | name, phone, email, website, category, address, rating, review count, then the six social columns (`--no-socials` drops them). The engine writes 36 raw columns plus `categories`; `--full` keeps them all. |
  158. | 📧 **Email extraction, on by default** | After the Maps job, the script crawls every business website, 16 at a time: the homepage, then its contact and about pages if the homepage shows no email. It prints your found rate. |
  159. | 🗺️ **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`. `--deep-scan` (`!` slower) goes further: any tile that comes back at the cap is split into 4 sub-tiles one zoom level in, so dense districts are searched block by block. |
  160. | 🔗 **Social enrichment, on by default** | Finds Instagram, Facebook, LinkedIn, TikTok, YouTube and X profiles in code (HTTP + regex), reusing the homepage the email crawl already fetched. Zero AI tokens. `--no-socials` skips it. |
  161. | 🎯 **Who already advertises** | `--tech` spots a Meta Pixel, Google Ads tag, analytics, Bing Ads, LinkedIn Insight and TikTok pixels on each website, plus its platform (WordPress, Shopify, Wix…) and mobile support, then ranks leads by an `intent_score` from 0 to 100. Zero AI tokens. |
  162. | 🧹 **Filters** | `--no-website` (businesses that still need a site), `--min-rating`, `--min-reviews`, `--has-phone`, `--has-email`, `--limit`. `--exclude earlier.csv` skips the places you already have, so a weekly re-run returns only new leads. |
  163. | ✅ **Email checks** | `--verify-emails` looks up each domain's MX record over DNS (no key), drops dead domains and labels the mail host (`google_workspace`, `microsoft_365`, `other`, `none`; blank when the row has no email). |
  164. | 📍 **Auto-geocoding** | Type a city name. Coordinates are resolved for you via OpenStreetMap. Repeat `--city` to run several cities into one file. |
  165. | 📦 **Batch jobs** | Many keywords, one job, one CSV. The engine lists a place found by several keywords once. |
  166. | 🌐 **Proxies** | For large or repeated runs: `--proxy URL` with `http`, `https`, `socks5` or `socks5h`, and `user:pass@` on `http` and `https`. Repeat it and the keywords take turns; a keyword Google refuses is retried through the next proxy. |
  167. | 🤖 **Agent-native** | A skill plus four slash commands. The agent runs the script and presents the lead fields; it never hand-builds API calls. |
  168. | 🔒 **Safe defaults** | API bound to `127.0.0.1`, and the engine refuses requests from other websites in your browser (DNS rebinding, cross-site posts); an optional API key. No telemetry: the engine talks to Google Maps, and to the businesses' websites and `dns.google` only for jobs that ask. The web UI and `engine.py status` ask GitHub once a day whether a newer release is out, with nothing about you in the request (`SCRAPER_NO_UPDATE_CHECK=1` in `.env` turns it off); nothing updates itself. Proxy passwords show as `***`. A cell that a spreadsheet would run as a formula gets a leading `'` in the engine's CSV download and in the script's file. Results git-ignored; website fetches skip private addresses; rate-limit and data-law guardrails built into the skill. |
  169. ### Measured, not estimated
  170. Fresh install of v2.1.0 on 2026-11-01: a MacBook, the installed Chrome, no Docker, no proxies, home internet. Every number below is one run, reproducible with the command shown.
  171. | Command | Result | Wall time |
  172. |---|---|---|
  173. | `scrape.py "coffee shops in Austin TX" 30.2672 -97.7431 --depth 2` | 40 places, 11 emails, 16 with a social profile | 21 s |
  174. | `scrape.py "dentists in Denver CO" --city "Denver, CO" --depth 5` | 100 places, 98 phones, 42 emails, 63 with a social profile | 44 s |
  175. | `scrape.py "restaurants in Manhattan NY" 40.7580 -73.9855 --depth 20 --no-email --no-socials` | 119 places (Google's cap) | 34 s |
  176. | `scrape.py "restaurants in Manhattan NY" --city "Manhattan, NY" --grid 3 --depth 6 --no-email --no-socials` | 471 unique places, 9 tiles | 5 min 21 s |
  177. | `scrape.py "roofing contractors in Phoenix AZ" --city "Phoenix, AZ" --depth 3 --tech --verify-emails --min-rating 4.0 --has-phone` | 59 places, 38 emails, ad pixels on 11 sites, sorted by `intent_score` | 29 s |
  178. | `scrape.py "cafes in Lisbon" --city "Lisbon, Portugal" --depth 2 --lang pt --country pt --reviews 3 --full` | 40 places with 3 reviews, a star histogram, the week's hours and photo URLs each | 37 s |
  179. Whole session: 2,068 places across 27 jobs in 21 minutes, no `unusual traffic` page. Your results depend on the city, the hour and your IP. Open-source alternatives, with sources: [docs/best-google-maps-scrapers.md](docs/best-google-maps-scrapers.md).
  180. ### Batch jobs and the Python CLI
  181. `scripts/scrape.py` is a standalone, dependency-free Python CLI: single queries, batches, geocoding,
  182. socials and CSV output. It works on macOS, Linux and Windows.
  183. ```bash
  184. python3 scripts/scrape.py --keywords-file examples/queries.example.txt --city "Denver, CO"
  185. ```
  186. One keyword per line. One job. One CSV.
  187. ---
  188. ## Honest limits
  189. - **About 120 listings per search.** Google Maps stops scrolling at roughly 120 results per search.
  190. That is Google's cap, not the kit's. `--grid` is the fix: it splits the city into N x N map tiles,
  191. runs one job per tile, and dedupes the results on `place_id`. Tiles run one at a
  192. time, so a grid is slower and more likely to trip rate limits than a single search. Each depth step
  193. adds a batch of about 20 places.
  194. - **Review counts come with a changed user agent.** Google gives a browser whose user agent says
  195. `HeadlessChrome` its "limited view": no review counts, today's hours only, no reviews. So the
  196. engine's headless Chrome sends its own user agent with `HeadlessChrome` replaced by `Chrome` (same
  197. OS, same version, nothing else changed), and Google returns `review_count`, the week's
  198. `open_hours` and `reviews_link`. Google can still leave a field out; if every count is missing,
  199. `--min-reviews` warns and skips that filter. Review texts and the star histogram come with
  200. `--reviews N` (up to 5 per place, one page load each). Business photo URLs come in `images`
  201. (`--full`), with no extra page loads. Rather run a real window, with the agent unchanged? [SETUP §3](SETUP.md#review-counts-hours-and-reviews).
  202. - **Emails only when a business publishes one.** The script reads the business homepage, then its
  203. contact and about pages. Listings with no site, or a site with no visible
  204. email, return an empty `emails` cell. Social links come from the homepage, or from the contact
  205. and about pages when the homepage has none. Instagram bios are not read. Expect emails on a fraction of
  206. rows, not all of them.
  207. - **A wrong website on the listing gives no emails or socials.** Some listings point at another
  208. business's site (a plumber listed with a bank's homepage). A homepage that shows neither the
  209. listing's phone number nor a word of its category is skipped for emails, social links and tech
  210. flags, and the run says how many were skipped. Report, abuse and phishing inboxes are dropped too.
  211. - **Rate limits are real.** Heavy use without proxies can get your IP temporarily rate-limited by
  212. Google for minutes to hours. When Google answers with its unusual-traffic page, the engine waits
  213. and retries the keyword up to 2 times, then stops the job and keeps the rows found before that.
  214. Your Google account is not affected. See [Responsible use](#responsible-use).
  215. - **The web UI is a simple form for beginners.** Up front are "What" (a business type) and "Where"
  216. (a city), and two options that are on by default: "Emails" and "Social profiles", under "Collect".
  217. Both boxes take only picks from their lists, and each pick becomes a tag you can remove: type a
  218. few letters, then pick. Text that is not in a list is refused, and Enter never starts a search.
  219. Three collapsed sections hold the rest: "Location
  220. and language", "Advanced options" and "Proxies". The job list shows each job's status with a
  221. progress bar (a review stage reads "reading reviews 7 of 20"), its times in your local time, and
  222. Leads CSV, Full CSV, JSON and Delete buttons. Downloads are named after the search, for example
  223. `bakery-in-portland-or-c063a815-leads.csv`. Leads CSV has the script's 8 lead fields and the social
  224. columns, with the same junk-email rules; Full CSV and JSON have every raw column. Its email and
  225. social options read homepages only, so the scripts, which also crawl contact pages, find more
  226. emails. Its What and Where boxes take only picks from their lists: about 4,100 business types
  227. (the kit's 201 popular ones in `engine/presets/business-types.json`, add a niche there, then
  228. Google's own category names) and about 168,000 cities from GeoNames, so a search never names a
  229. place or a type that does not exist. Each type is searched in each city, one job per city, with
  230. the map centred on that city. The page loads two static files from GitHub
  231. (`raw.githubusercontent.com`), with no tracking: the sponsor box's
  232. `assets/sponsors/sponsors.json` from this repo (cached for a day), and Google's category names
  233. for the What box (cached for 30 days). Scraped data stays on your machine.
  234. - **Service-area businesses often have no address.** Plumbers, cleaners and other mobile services
  235. often hide their street address on Google, so `address` is empty for them. The city and the phone
  236. usually remain.
  237. - **No SOCKS5 login.** Chrome cannot log in to a SOCKS5 proxy, so the engine refuses a SOCKS5 proxy
  238. with a username and password (422). Use the provider's `http://user:pass@host:port` address, or a
  239. SOCKS5 proxy that allows your IP address.
  240. ---
  241. ## How it compares
  242. **14 of 14 green. No other Google Maps scraper we compared scores more than 5.** The kit is the only
  243. one that finds emails, social profiles and ad pixels by default, for free, without the data leaving your machine.
  244. ✅ built in and free · 🟡 partial, manual or paid · ❌ no · ➖ not applicable or not stated
  245. | | **This kit** | [gosom](https://github.com/gosom/google-maps-scraper) | [omkar&shy;cloud](https://github.com/omkarcloud/google-maps-scraper) | [zohaib&shy;bashir](https://github.com/zohaibbashir/Google-Maps-Scrapper) | [gaspa93](https://github.com/gaspa93/googlemaps-scraper) | [conor](https://github.com/conor-is-my-name/google-maps-scraper) | Apify, Out&shy;scraper |
  246. |---|---|---|---|---|---|---|---|
  247. | Price | ✅ Free | ✅ Free | 🟡 Freemium | ✅ Free | ✅ Free | ✅ Free | ❌ Per result |
  248. | Data stays local | ✅ | ✅ | 🟡 Cloud enrichment | ✅ | ✅ | ✅ | ❌ |
  249. | Setup | ✅ Python, Chrome | 🟡 Docker or binary | 🟡 App, account | 🟡 pip, Playwright | 🟡 pip, Chrome&shy;driver | 🟡 Docker | 🟡 Account, key |
  250. | Past Google's 120 cap | ✅ `--grid`, `--deep-scan` | 🟡 Manual bbox | ✅ | ❌ | ❌ | ❌ | ✅ |
  251. | Emails | ✅ On by default | 🟡 Flag, off by default | 🟡 Paid | ❌ | ❌ | ❌ | 🟡 Paid add-on |
  252. | Email check (MX) | ✅ `--verify-emails` | ❌ | 🟡 Paid | ❌ | ❌ | ❌ | 🟡 Paid add-on |
  253. | Social profiles | ✅ 6 networks, on by default | ❌ | 🟡 Paid | ❌ | ❌ | ❌ | 🟡 Paid add-on |
  254. | Ad pixels and lead score | ✅ `--tech` ranks leads | ❌ | 🟡 Yes/no ads field | ❌ | ❌ | ❌ | ❌ |
  255. | Lead filters | ✅ 6 filters and `--exclude` | 🟡 `-resume` only | ✅ | ❌ | ❌ | ❌ | 🟡 Varies |
  256. | Proxy rotation | ✅ Rotates on block | ✅ | ➖ | ❌ | ❌ | ❌ | ✅ |
  257. | Web UI | ✅ | ✅ | ✅ App | ❌ | ❌ | ❌ | ✅ |
  258. | REST API | ✅ Localhost only | ✅ | ✅ | ❌ | ❌ | ✅ | ✅ |
  259. | AI agent | ✅ Skill and 4 commands | 🟡 Needs Docker and Node | ❌ | ❌ | ❌ | ❌ | 🟡 Apify MCP |
  260. | Published speed | ✅ 100 leads with emails in 44 s | 🟡 ~120 a minute, emails off | ❌ | ❌ | ❌ | ❌ | ➖ |
  261. | **✅ count** | **14 / 14** | 5 | 4 | 2 | 2 | 3 | 4 |
  262. Facts about other tools come from their own README on 2026-11-02. The kit's numbers are measured, with
  263. the commands to reproduce them, in [Measured, not estimated](#measured-not-estimated). The full
  264. comparison is in [docs/best-google-maps-scrapers.md](docs/best-google-maps-scrapers.md).
  265. Ask a chat AI to "scrape Google Maps" and it hits a consent wall and JavaScript-rendered pages, so
  266. you get close to zero structured rows: on the table above it would score 1, for its free tier. This kit runs a real headless scraping engine locally and gives
  267. the agent a precise operating manual for it.
  268. ---
  269. ## Guides and recipes
  270. One page per job, with the exact commands. Index: [docs/README.md](docs/README.md).
  271. - [Google Maps email scraper: how the kit finds business emails](docs/google-maps-email-scraper.md)
  272. - [Google Maps scraper in Python: every CLI flag](docs/google-maps-scraper-python.md)
  273. - [Google Maps scraper without an API key](docs/google-maps-scraper-no-api-key.md)
  274. - [Scrape Google Maps leads with Claude Code](docs/scrape-google-maps-leads-with-claude-code.md)
  275. - [Best open-source Google Maps scrapers on GitHub, compared](docs/best-google-maps-scrapers.md)
  276. - Recipes: [dentists](docs/recipes/dentist-leads.md), [roofing contractors](docs/recipes/roofing-contractor-leads.md), [restaurants](docs/recipes/restaurant-leads.md)
  277. ---
  278. ## FAQ
  279. ### What is the best free Google Maps scraper on GitHub?
  280. For lead lists with contact data, this kit: it is the only open-source scraper that returns emails and social profiles by default, needs no Docker, API key or pip install, and gets past Google's 120-result cap with `--grid` and `--deep-scan`. The comparison, with sources and dates: [docs/best-google-maps-scrapers.md](docs/best-google-maps-scrapers.md).
  281. ### How fast is it?
  282. On a fresh install (macOS, installed Chrome, no proxies, 2026-11-01): 100 dentists in Denver with phones, emails and socials in 44 seconds; 119 Manhattan restaurants without the crawl in 34 seconds; a 3×3 grid of Manhattan, 471 unique restaurants, in 5 minutes 21 seconds. Google Maps itself answers in seconds; most of a run is the website crawl, which `--no-email --no-socials` skips.
  283. ### Is this Google Maps scraper free?
  284. Yes. The kit and its engine are MIT licensed. There are no credits, subscriptions or API keys. You
  285. need Python and Chrome on your own machine, or Docker.
  286. ### Do I need a Google Maps API key or the Google Places API?
  287. No. The kit drives a headless browser against Google Maps directly, so there is no API quota or billing.
  288. ### How is this different from kit 1.x?
  289. Kit 1.x ran another open-source scraper's engine in Docker. Kit 2.0 has its own engine, written
  290. from scratch in standard-library Python around a headless Chrome. It runs without Docker, works on
  291. Windows and on arm64 Linux, needs no workarounds for jobs that never finish, and sends no telemetry.
  292. It keeps the same job API and column names, so scripts and files made for 1.x still work, and an
  293. update from 1.x brings the old jobs along. A few columns hold their data differently (reviews come
  294. on request, without reviewer names): [SETUP, Upgrading from kit 1.x](SETUP.md#upgrading-from-kit-1x). On top sits the lead-focused layer: a dependency-free
  295. Python CLI with geocoding and batching, email and social enrichment to a clean CSV, and a
  296. Claude Code skill with slash commands and safety guardrails. See [CREDITS.md](CREDITS.md).
  297. ### Do I need Claude Code to use it?
  298. No. Claude Code makes it hands-free through a skill and slash commands, but `scripts/scrape.py` and
  299. `scripts/scrape.sh` run on their own from any terminal.
  300. ### Can ChatGPT or Claude scrape Google Maps?
  301. Not by chatting alone. A chat AI hits Google's consent wall and pages built by JavaScript, so it
  302. returns few or no structured rows. An agent that can run commands, such as Claude Code, Codex or
  303. Cursor, can drive this kit: ask "scrape gyms in Miami" and it runs the script, then returns a table
  304. and a CSV. See [Use it with Claude Code or any agent](#use-it-with-claude-code-or-any-agent).
  305. ### Does it work with Codex, Cursor or other agents?
  306. Yes. `npx skills add mahanaicoach/google-maps-scraper-kit` installs the skill into any Agent
  307. Skills-compatible tool. The `/scrape` slash commands are Claude Code only. After a scrape, Claude Code,
  308. Codex and Gemini CLI show you the first 10 rows in the chat through the kit's hook, which the model
  309. never receives. In other agents, `python3 scripts/leads.py <file> --open` opens the file in your
  310. spreadsheet app.
  311. ### What data do I get for each business?
  312. Name, phone, email, website, category, address, rating and review count, then Instagram, Facebook,
  313. LinkedIn, TikTok, YouTube and X links by default. Add `--no-socials` to drop the social columns, or
  314. `--full` for every raw column.
  315. ### How many leads can I scrape?
  316. Up to about 120 per search. Add `--grid 3` to split the city into 9 map tiles and get past that cap, or
  317. `--deep-scan` to also split every tile that hits the cap into 4 sub-tiles (slower, marked `!`),
  318. with duplicates removed. Batch as many keywords as you like in one job. For large or repeated runs,
  319. add proxies (see [Responsible use](#responsible-use)).
  320. ### Does it work on Windows, Linux and Apple Silicon Macs?
  321. Yes, natively on all three with Python and Chrome, Apple Silicon and Linux arm64 included, or anywhere
  322. Docker runs. On Windows, use `py scripts/scrape.py`, or run `scrape.sh` under WSL2 or Git Bash.
  323. [SETUP.md](SETUP.md) has the platform notes.
  324. ### Is scraping Google Maps legal?
  325. It is against Google's Terms of Service, and phones and emails are personal data. Read
  326. [Responsible use](#responsible-use) and follow the law where the data is used: GDPR and CCPA
  327. abroad, and LGPD in Brazil. This is not legal advice.
  328. ---
  329. ## Responsible use
  330. This drives a real scraper against Google Maps. Light use is fine. Heavy use without proxies can get
  331. your IP **temporarily rate-limited** (minutes to hours). Your Google account is not affected.
  332. - Run one job at a time. Start at `depth 5` and raise only when needed.
  333. - Watch for block signals: `failed` jobs, empty results, or far fewer rows than an identical earlier run.
  334. - Add proxies for large or repeated runs: `--proxy http://user:pass@host:port` on the script
  335. (repeatable), or the `"proxies"` array on the raw API. URL-encode special characters in the
  336. username or password. With several proxies the keywords take turns, and a keyword Google refuses,
  337. or whose proxy fails, is retried through the next one. SOCKS5 works only without a username and
  338. password. Proxy passwords show as `***` in the API and the web UI and never reach the log. Sponsor
  339. [Swiftproxy](https://www.swiftproxy.net/?ref=googlemapsscraperkit) takes 10% off with code `PROXY90`:
  340. ```json
  341. "proxies": ["http://user:pass@host1:port", "http://user:pass@host2:port"]
  342. ```
  343. - Treat output as leads to verify, not a dataset to resell. Phones and emails are personal data:
  344. follow GDPR, CCPA, CAN-SPAM and, in Brazil, LGPD — including the lawful basis, the purpose and an
  345. opt-out before any outreach.
  346. For large requests, the agent flags the risk and suggests proxies, then proceeds. It refuses only
  347. clearly abusive use.
  348. ---
  349. ## Featured in
  350. - [Best Google Maps Scrapers on GitHub in 2026 (Tested)](https://scrap.io/google-maps-scraper-github-open-source-guide) by Scrap.io
  351. ## Star history
  352. If this kit saved you an afternoon of copy-pasting, a star helps the next person find it.
  353. <a href="https://www.star-history.com/#Mahanaicoach/google-maps-scraper-kit&Date">
  354. <img src="https://api.star-history.com/svg?repos=Mahanaicoach/google-maps-scraper-kit&type=Date" alt="Star history chart for Mahanaicoach/google-maps-scraper-kit" width="600">
  355. </a>
  356. <details>
  357. <summary><strong>Project layout</strong></summary>
  358. ```
  359. google-maps-scraper-kit/
  360. ├── engine/ the kit's own engine: Google Maps over Chrome DevTools, HTTP API, web UI
  361. │ ├── serve.py the engine server on 127.0.0.1:8080
  362. │ └── test_engine.py offline tests, no network, no Chrome
  363. ├── Dockerfile the engine image: Python + Debian's Chromium, non-root
  364. ├── docker-compose.yml runs that image on 127.0.0.1:8080
  365. ├── .env.example config template
  366. ├── scripts/
  367. │ ├── engine.py start, stop, status or restart the engine without Docker; list or delete jobs
  368. │ ├── scrape.py Python CLI: single, batch, geocoding, socials, CSV
  369. │ ├── scrape.sh bash CLI: single query
  370. │ ├── update.sh one-command update of a clone or fork
  371. │ ├── test_scrape.py offline tests, no network: python3 scripts/test_scrape.py
  372. │ └── test_update.sh checks update.sh, no network: bash scripts/test_update.sh
  373. ├── docs/ guides and recipes
  374. ├── examples/ sample job body and batch keyword list
  375. ├── .claude/
  376. │ ├── settings.json pre-approved local commands for hands-free runs
  377. │ ├── commands/ /scrape, /scrape-batch, /scrape-setup, /scrape-jobs
  378. │ └── skills/google-maps-scraper/SKILL.md
  379. ├── AGENTS.md points Codex, Cursor and other agents to CLAUDE.md
  380. ├── CLAUDE.md project instructions for Claude Code
  381. ├── CREDITS.md attribution and licenses
  382. └── SETUP.md full setup guide
  383. ```
  384. </details>
  385. ## Updating
  386. The web UI shows a line under its title when a newer release is out, and `python3 scripts/engine.py status`
  387. prints one (both check GitHub's releases once a day; `SCRAPER_NO_UPDATE_CHECK=1` in `.env` turns it off).
  388. Nothing updates by itself. Pull the latest fixes with one command. It works in a clone of this repo or of your fork, and it
  389. keeps your own commits:
  390. ```bash
  391. bash scripts/update.sh
  392. ```
  393. If the engine runs in Docker, the script rebuilds and restarts it so the new version takes effect.
  394. Without Docker, restart it yourself: `python3 scripts/engine.py restart`. Forked it on GitHub? Run `git push` afterwards, or click **Sync fork** on your fork's
  395. page.
  396. On Windows without Git Bash, run the same update by hand:
  397. ```bash
  398. git pull https://github.com/Mahanaicoach/google-maps-scraper-kit.git master
  399. py scripts/engine.py restart
  400. ```
  401. With Docker, run `docker compose up -d --build --remove-orphans` in place of the second line.
  402. Coming from kit 1.x? The same command moves you to the own engine, and your old jobs and their CSVs
  403. appear in the new web UI. Details: [SETUP.md, upgrading from 1.x](SETUP.md#upgrading-from-kit-1x).
  404. ## Support
  405. Found a bug? [Open an issue](https://github.com/Mahanaicoach/google-maps-scraper-kit/issues/new/choose) with
  406. the command you ran and the error. Issues are for problems with the kit. Run your own scrapes with the
  407. quick start above; requests like "find me hotels in Hamburg" are closed without action.
  408. Contributions: [CONTRIBUTING.md](CONTRIBUTING.md). Security reports: [SECURITY.md](SECURITY.md).
  409. ## License
  410. Built by [Mahan](https://github.com/Mahanaicoach). MIT licensed. Third-party components: [CREDITS.md](CREDITS.md).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.