Google Maps Scraper Kit: What 673 Stars, 3 Open PRs, and Google's ToS Actually Mean

TL;DR

• It’s a thin wrapper, not a new scraper. google-maps-scraper-kit is Docker Compose, two helper scripts, and a Claude Code Skill built around gosom/google-maps-scraper, a much older, MIT-licensed engine with 5,943 stars and 942 forks. The kit’s own CREDITS.md says as much.
• Real code activity stopped June 29, 2026 — the “last pushed” date is misleading. The repo shows a September 7 push, but that commit is on an unrelated branch (a personal marketing-carousel skill for the maintainer’s own use) that never touched the scraper and was never merged. The four commits that built the actual kit all landed June 21–29.
• All three open pull requests are real bug reports from strangers, and none are merged. Two fix a broken macOS setup path (an unbound-variable bash crash, a dead Playwright driver CDN); one bumps a pinned Docker image tag to stop jobs from hanging forever. As of this writing, the maintainer hasn’t commented on any of them.
• The upstream engine now ships its own competing agent skill — added March 21, 2026 and substantially upgraded in July, maintained by the same person who maintains the actual scraper. Neither README mentions it, and it changes why you’d pick this kit over the source it wraps.
• The fork-to-star ratio really is unusual — 119 forks per 673 stars (17.7%) versus roughly 16% even for the far larger upstream project, and nowhere near the low-single-digit ratio typical of most repos. The likely driver: the kit hit Trendshift’s trending list, and people forking a trending repo to self-host or customize it inflates forks faster than stars.
• The legal risk is exactly what the README says it is, no more, no less: scraping Google Maps breaches Google’s Terms of Service (a contract issue), can get your IP temporarily rate-limited (not your account banned), and any phone numbers or emails you collect are personal data subject to GDPR/CCPA/CAN-SPAM. We found zero DMCA notices, lawsuits, or takedowns against either repo in this research.

Google Maps scraping projects show up on GitHub constantly, and most are indistinguishable from each other: a scraper, a README, a handful of stars. google-maps-scraper-kit stands out for a narrower reason — it doesn’t scrape anything itself. It hands the actual scraping to a different, established open-source project and adds exactly one thing: a Claude Code Skill that lets you say “scrape coffee shops in Austin” and have Claude create the job, poll it, download the results, and hand you a clean CSV. That’s a genuinely useful idea, and also one with a large asterisk hanging over it, since the thing it automates access to sits squarely against Google’s Terms of Service. We pulled the repo’s real commit history, its open pull requests, its maintainer’s other projects, and the upstream engine’s own issue tracker to see what’s actually there versus what a skim of the README would suggest.

What the kit actually does

The pitch, straight from the README, is “the difference between can’t and can”: a chat AI trying to fetch maps.google.com directly hits a consent wall and JavaScript-rendered content and gets back roughly zero structured results. This kit sidesteps that by running the real scraping engine — gosom/google-maps-scraper by Georgios Komninos, a Go-based Playwright scraper first published in April 2023 — in a local Docker container bound to 127.0.0.1:8080, and teaching Claude the exact REST API contract to drive it.

The mechanics, pulled straight from the kit’s own SKILL.md: you POST /api/v1/jobs with keywords, coordinates, and a depth setting; Claude polls GET /api/v1/jobs/{id} in the background until the status flips from working to ok; then it downloads a CSV via GET /api/v1/jobs/{id}/download. The raw scrape returns 34 fields per business — everything from plus_code to popular_times to reviews_per_rating — and the kit’s real value-add is stripping that down to eight fields anyone doing outreach actually wants: name, phone, email, website, category, address, rating, and review count. Optional social-profile enrichment (Instagram/Facebook/LinkedIn) runs as plain HTTP + regex against each business’s own website, at zero LLM token cost, which is a small but genuinely well-thought-out detail — most “AI does X” wrappers would burn tokens on that instead of writing five lines of code.

None of that is upstream’s work being copied badly — it’s real orchestration on top of a real, independently substantial project. The LICENSE file, despite GitHub’s API flagging it NOASSERTION, is a real MIT license with a custom preamble scoping it to “the wrapper (Docker Compose setup, scripts, documentation, and Claude skill) ONLY,” explicitly crediting Komninos’s separate 2023 MIT license for the scraping engine itself. GitHub’s SPDX detector likely trips on that added preamble paragraph rather than on any actual licensing problem — the CREDITS.md file reproduces Komninos’s full license text as MIT itself requires when redistributing an unmodified upstream Docker image.

The thing neither README mentions: upstream now ships its own agent skill

Here’s a finding that changes the calculus on why this kit exists at all. gosom/google-maps-scraper — the engine this kit wraps — added its own skills/google-maps-scraper directory starting March 21, 2026, three months before this kit was created, and shipped a substantial upgrade, “feat: add AI agent-guided scraping workflow” (#314), on July 22, 2026 — adding an agent-first setup flow, masked proxy-credential handling, proxy-sponsor guidance, and crawl monitoring. Neither this kit’s README, CHANGELOG, nor CREDITS.md mentions that the upstream project it depends on has its own, independently maintained answer to the exact problem it was built to solve.

That matters for anyone deciding whether to install this specific kit versus using gosom’s own skill directly: the upstream version is maintained by the same person who maintains the actual scraping engine, rather than a third party’s Docker Compose file and .claude/settings.json permissions layer sitting on top of it. This kit hasn’t stopped working, and its own engineering (the 34-to-8 field cleanup, the zero-token social enrichment) is still real, independent value. But “why use the wrapper instead of the thing it wraps” is a harder question to answer today than it was when this kit launched in June.

The repo’s real activity: three unmerged PRs, one closed issue, and a misleading push date

Pulled live from the GitHub API on September 20, 2026: the repo was created June 21, 2026, has 673 stars, 119 forks, 3 watchers, and shows a last-pushed date of September 7, 2026. Here’s what’s actually behind those numbers.

The commit history is four commits, all by the maintainer, all in an eight-day window:

Commit	Date	What it did
fa805c6	Jun 21, 2026	Initial commit — the kit’s Docker Compose setup, scripts, and skill
b3a444f	Jun 21, 2026	Optional social profile extraction (Instagram/Facebook/LinkedIn)
0e8d980	Jun 29, 2026	README update
a6a39d1	Jun 29, 2026	Emails on by default, ask before socials, CSV output default

That’s it — no commits on master since June 29. So why does GitHub report the repo as pushed on September 7? Because a second branch, claude/carousel-script-ideas-5vsuez, was pushed that day, authored by “Claude” (co-authored by Claude Opus 5 per the commit trailer) — and it has nothing to do with the scraper. It adds a .claude/skills/mahan-carousel/ folder: a personal skill for generating the maintainer’s own social-media marketing carousels, grounded in “the system actually built in the Carousel Covers and Carousel Design Review artifacts.” It was never merged into master. GitHub’s “last pushed” field reflects any branch, which is a genuine footgun for judging a repo’s health from the API alone — this one would read as “updated two weeks ago” when the actual product hasn’t changed in nearly three months.

All three open pull requests are unmerged, unaddressed, and from strangers, not the maintainer:

• PR #1, opened September 15 by luscabrandao: the docker-compose.yml pins the upstream image at v1.15.0, but that build downloads a Playwright driver from playwright.azureedge.net that Microsoft has since pulled — every job hangs in working forever with could not install driver: ... got non 200 status code: 404. The fix bumps the pinned tag to v1.18.0. The PR description includes a real test run against Brazilian pizzarias to confirm the fix.
• PR #3, opened September 19 by ranpatcheck: scripts/scrape.sh crashes with AUTH[@]: unbound variable on stock macOS bash 3.2 (the version Apple ships without Homebrew) whenever no SCRAPER_API_KEY is set — which is every default local run, since .env.example treats the localhost binding itself as the security boundary. The fix guards the array expansion; the PR includes a reproduced failing case and a verified passing run.
• PR #4, also from ranpatcheck, September 19: a documentation PR covering three separate first-run blockers on a clean Apple Silicon Mac — a broken docker compose symlink left behind after uninstalling Docker Desktop, a full VM disk from Colima/Lima, and the same dead Playwright driver CDN as PR #1, but for the no-Docker native install path. It also flags, correctly, that the bare go install binary defaults to -addr :8080 on all interfaces with no authentication, unlike the Docker path where the port mapping enforces the localhost boundary.

One issue, #2, was opened and closed the same day (September 15) by a different user with no body text and no comments — essentially noise, not a real bug report.

Notably, ranpatcheck’s GitHub profile (Ranshoshan) is itself a fork of the kit, meaning the two most substantive open PRs came from someone who forked the repo specifically to fix it rather than just to star it — a small, concrete data point behind the unusually high fork count. As of this writing, none of the three PRs have a maintainer comment, review, or merge.

Is a two-and-a-half-month-old codebase abandoned, or just finished?

“Abandoned” implies someone stopped maintaining something they intended to keep maintaining. The evidence here points somewhere more specific: Mahanaicoach (GitHub handle for “Mahan Ai,” account created February 2026) has eight public repositories, and google-maps-scraper-kit’s 673 stars dwarf every other one — the next highest is competitor-x-ray at 12. Most of the other repos describe themselves explicitly as marketing tools: “[a]lex-hormozi-coach… A lead magnet by Mahan AI,” “[f]unnel-spy… A lead magnet by Mahan Ai,” “[c]ontent-repurposer… A distributable Claude skill.” The pattern that emerges is a solo builder shipping small, self-contained, free Claude Skills as lead magnets, one after another, rather than a maintainer committed to iterating any single one indefinitely. The unmerged mahan-carousel branch — a tool for generating marketing carousels to promote exactly this kind of project — fits that pattern precisely.

That reframes the “2-week-stale” framing from the brief: the real gap since a functioning feature shipped is closer to 12 weeks, and the three community PRs sitting open for one to five days (as of this writing) look less like neglect and more like a maintainer who has moved on to the next lead magnet before the current one’s bug reports came in. Worth knowing before you build a dependency on it — this isn’t a project with a maintenance cadence you can plan around either way.

The fork surge, visualized

The kit’s 119-forks-per-673-stars ratio (17.7%) isn’t an outlier next to its own upstream, which itself runs at 15.9% (942 forks / 5,943 stars) — high fork ratios seem to be a trait of the whole “run this locally and tweak it” category of scraper repo, not a red flag specific to this kit. The GitHub events feed for the kit repo (its most recent ~300 public events as of this writing) breaks down to 246 watch events, 48 fork events, 3 pull request events, 2 issue events, and 1 review — a fork for roughly every five stars in the most recent activity window, consistent with the overall ratio. A Trendshift listing puts it on a trending-repos tracker, which plausibly explains the volume: trending exposure draws people who fork to inspect, self-host, or customize a tool immediately, at a higher rate than people who simply star something to look at later.

The legal and rate-limiting picture — what both READMEs actually say

The kit doesn’t bury this. Its README opens with a blockquote warning before the fold: “Scraping Maps is against Google’s ToS — use responsibly,” and a full Rate limits, bans & responsible use section spells out the mechanism — big jobs back-to-back, high depth, many keywords, or scheduled runs without proxies can get your IP “temporarily rate-limit[ed]/block[ed]” for “minutes–hours,” during which jobs come back failed or empty. It’s explicit that this does not ban your Google account, recommends starting at depth 5, one job at a time, and frames output as “leads to verify, not a redistributable dataset.” The skill’s own behavior, per its instructions to Claude, is to “warn, don’t block” — flag the risk on a large scrape, suggest proxies, then run it anyway, refusing only “clearly abusive use.”

That guidance is inherited almost verbatim from upstream. Gosom’s own README carries a formal “Legal Notice”: “Please use this scraper responsibly and in accordance with applicable laws and regulations. Unauthorized scraping may violate terms of service,” plus a separate warning that its beta “Fast mode” specifically risks blocking. That guidance isn’t theoretical — the upstream issue tracker has real, multi-user threads about it. Issue #26, “Scraper stops after ~3-5 minutes,” is a long thread where multiple users report jobs stalling after a few minutes regardless of IP rotation; one, darealdemayo, laid out the actual pattern: “when I start the scraper, it takes less than one second per job and it slowly increases to almost 6 seconds per job… thus, I would guess that what we are seeing here is some sort of rate limitation.” Issue #24 is what led the maintainer to add SOCKS5 proxy support in response to a user asking about IP rotation services. And a still-open, unmerged pull request, #277, directly validates the kit’s own “consent wall” framing from the other direction: “Google Maps redirects to consent.google.com in GDPR regions, causing detail page timeouts,” proposing a fix that navigates to the Maps homepage first and clicks through consent so the resulting cookie persists. In other words, even a real, mature, Playwright-driven scraper still hits the EU consent wall as of this writing — the kit isn’t overstating the problem it’s solving.

What we searched for and found nothing on: DMCA notices, cease-and-desist letters, lawsuits, or takedown requests against either repository, or against Google Maps scrapers generally as a documented pattern. GitHub’s search API returned zero results for “dmca,” “cease,” “lawsuit,” or “takedown” scoped to the upstream repo’s issues and pull requests. That absence is worth stating plainly rather than implying legal action is imminent just because it fits the genre.

On the broader legal landscape: the closest real precedent is hiQ Labs v. LinkedIn, where the Ninth Circuit held that scraping data a site makes publicly accessible, without logging in, doesn’t violate the Computer Fraud and Abuse Act — but the case ultimately settled in December 2022 with hiQ agreeing to a $500,000 judgment, partly over its use of fake accounts to reach non-public data, which is a meaningfully different fact pattern than reading public Maps listings. The practical shape of the risk for a tool like this: a CFAA-style computer-crime claim is unlikely for logged-out, public-listing scraping, but a Terms of Service breach is a contract question independent of that, and any phone number or email address collected is personal data squarely inside GDPR, CCPA, and CAN-SPAM regardless of how it was obtained — which is exactly the boundary both READMEs draw.

Who else is involved

The kit itself has a single commit author — the maintainer. Its two most substantive open PRs came from ranpatcheck (who also maintains their own fork of the repo) and a third from luscabrandao. Coverage beyond GitHub is thin but real: a Medium writeup by Nitin Gavhane (July 2026) walks through the setup for a non-technical audience, and a post on X from @itsvlady pitched it as a way to “pull unlimited local leads off Google Maps for free.” We found no Reddit threads, Hacker News discussion, or YouTube videos specifically covering this kit (as opposed to the broader “scrape Google Maps with Claude Code” idea, which several unrelated videos and tools address) — worth stating explicitly rather than padding the research with tangentially related content.

The honest read

This is a well-executed, honestly documented wrapper around someone else’s substantial, actively used open-source scraper — not a novel scraping breakthrough, and it doesn’t claim to be one. The engineering choices that matter (stripping 34 raw fields to 8 useful ones, doing social enrichment with zero LLM tokens, binding to localhost by default, warning before the fold instead of burying the ToS risk in a footnote) are good instincts. The parts that matter if you’re deciding whether to depend on it: it’s had zero commits to its core code in roughly three months, all three open pull requests are unaddressed bug fixes from strangers, and its maintainer’s broader body of work suggests a build-and-move-on pattern rather than long-term stewardship. None of that makes it unsafe to try for a one-off lead list. It does mean you’re on your own if the pinned Docker image breaks again the way PR #1 describes, at least until someone else’s fork fixes it first.

If you’re evaluating this kind of tool as part of a wider stack, our comparison of seven GitHub email scraper projects uses the same live-stats-over-star-count approach, and our running list of trending GitHub repositories covers other projects riding the same kind of visibility spike. If the idea of an AI agent driving a local Docker service with no authentication gives you pause, our vibe-coding security checklist and our piece on the skills.sh credential-theft campaign are both relevant background before installing any third-party Claude Skill you didn’t write yourself. And if you’re curious how a small, single-maintainer setup like this one compares to a documented production workflow, we’ve written up how this blog itself runs on Claude Code and a custom MCP server.

FAQ

Is google-maps-scraper-kit its own scraper, or does it depend on another project? It’s entirely a wrapper. All scraping happens inside the official Docker image of gosom/google-maps-scraper by Georgios Komninos; the kit adds Docker Compose config, two convenience scripts, and a Claude Code Skill on top, and says so explicitly in its own CREDITS.md.

Why does GitHub show this repo as recently updated if development stopped in June? GitHub’s “pushed_at” field reflects a push to any branch. A branch pushed September 7, 2026 added an unrelated personal marketing-carousel skill for the maintainer’s own use — it was never merged into master, and the scraper’s actual code hasn’t changed since June 29, 2026.

Are the open pull requests safe, tested fixes? They read as genuine, well-documented bug fixes with reproduction steps and verified test runs (a dead Playwright driver CDN, a macOS bash crash, and Docker/native setup blockers). None have been merged or commented on by the maintainer as of this writing, so treat them as community-contributed patches you’d need to apply yourself, not confirmed-safe upstream code.

Can scraping Google Maps get me banned? Per both the kit’s and upstream’s documentation, no — it can get your IP temporarily rate-limited or blocked for minutes to hours, not your Google account banned. It is, however, a breach of Google’s Terms of Service, which is a contract matter distinct from any ban.

Is it legal to scrape Google Maps? Case law like hiQ Labs v. LinkedIn suggests scraping logged-out, publicly visible data likely doesn’t violate the U.S. Computer Fraud and Abuse Act, but that’s a narrow point about computer-crime law, not a blanket “it’s fine.” It still breaches Google’s ToS as a contract matter, and any phone numbers or emails you collect remain personal data subject to GDPR, CCPA, and CAN-SPAM regardless of how you obtained them.

Why does the license show as “NOASSERTION” on GitHub if the repo says it’s MIT? The actual LICENSE file is real MIT text, but with an added preamble paragraph scoping it to just the wrapper code and crediting the separate upstream license for the scraper engine. GitHub’s automated SPDX license detector likely can’t parse that custom preamble, which is a detection quirk, not evidence of a licensing problem.

Has anyone filed a legal complaint against this kit or its upstream project? Not that this research found. A search of the upstream project’s issues and pull requests for DMCA notices, cease-and-desist mentions, lawsuits, or takedown requests returned nothing, and no such reports turned up in web search either.