Google Maps Scraper Kit: a local wrapper that lets Claude run gosom/google-maps-scraper

What Google Maps Scraper Kit adds to gosom/google-maps-scraper

The kit is a thin wrapper. The actual scraping engine is gosom/google-maps-scraper by Georgios Komninos, which the README credits and describes as MIT licensed. Everything the kit contributes sits around that engine: a docker-compose.yml that pins the image to gosom/google-maps-scraper:v1.15.0, a bash script and a dependency-free Python script, a Claude Code skill under .claude/skills/google-maps-scraper/SKILL.md, and a README that spends most of its length on rate limits and data handling.

So the audience is narrow and specific. If you are comfortable running upstream's Go binary and reading its documentation, the wrapper buys you little. If you want one command to get a local API on port 8080 and a natural-language front end that knows the create, poll, download sequence, the kit is aimed at you. The output shape confirms the intent: the README says the scraper captures roughly 34 raw fields but the kit strips geo coordinates, IDs, hours, images and review blobs, leaving name, phone, email, website, category, address, rating and review count. That is a lead list, not an archive.

The README also states a comparison it does not substantiate with a method: asking a chat AI to fetch maps.google.com directly hits a consent wall and JavaScript-rendered content, so it returns almost no structured results, while the kit returns dozens to hundreds of rows per query. Treat that as the author's claim. No test procedure, dataset or date is given for it.

How the local scraper actually runs: Docker, 127.0.0.1 and the job API

The architecture is one container. docker-compose.yml declares a single service on the pinned image, starts it with the command ["-web", "-data-folder", "/gmapsdata"], and maps the port as 127.0.0.1:8080:8080. Two named volumes persist state: gmaps_data at /gmapsdata holds job results, and gmaps_cache at /opt holds the Playwright browser cache so restarts are faster.

The localhost binding is the whole security model, and the compose file says so in a comment: the image has no built-in auth, so 127.0.0.1 is the boundary, and the port mapping should not be changed to 0.0.0.0 or a public interface without an auth proxy in front. .env.example repeats this. SCRAPER_BASE_URL defaults to http://localhost:8080 and SCRAPER_API_KEY is left blank because no key is required locally; the file says the key is only needed if you later expose the scraper behind something like Caddy or nginx that checks an X-API-Key header.

Work flows through a job API. You create a job, poll it, then download results. The README's own health check is a GET against /api/v1/jobs, which it says should return a JSON list, probably empty. The Claude skill exists to run that create, poll, download, clean sequence in the right order. One detail worth noting: the published image is linux/amd64, so on Apple Silicon it runs under emulation, and the compose file tells you to uncomment the platform: linux/amd64 line if it will not start. That is a real constraint, not a footnote.

Installing the kit and running a first scrape

The README gives a three-step quick start and points to SETUP.md for the full version. Docker Desktop is the only prerequisite it names. The first command starts the scraper in the background; the compose file sets restart: unless-stopped, so it comes back after a reboot.

docker compose up -d

Then confirm the API is answering. The README says this should print a JSON list, probably empty.

curl http://localhost:8080/api/v1/jobs

The bash script takes a query, a latitude, a longitude and a depth. The README's example is Austin, Texas at depth 5, and it recommends starting at depth 5 rather than higher.

./scripts/scrape.sh "coffee shops in Austin TX" 30.2672 -97.7431 5

If you prefer Python, scripts/scrape.py is described as having no dependencies, and --full returns all the raw fields instead of the trimmed lead list. The README also documents an optional --socials flag that scans each business's website for Instagram, Facebook and LinkedIn links; it says that runs in code with HTTP and regex, costs nothing in tokens, is slower because it fetches one site per business, and has partial coverage because it only finds socials a business actually links.

Inside Claude Code, the skill auto-triggers on phrases like "scrape coffee shops in Austin" and there are slash commands, including /scrape <business> in <city, ST> [depth], /scrape-batch with a keywords file, /scrape-setup and /scrape-jobs. The example files live at examples/queries.example.json and examples/queries.example.txt.

Rate limits, IP blocks and the cases where you should not use it

The kit is candid about its failure mode, and this is the part worth reading before anything else. The README warns that over-use can get your IP temporarily blocked: big jobs back-to-back, very high depth, many keywords at once, or scheduled runs without proxies. The stated consequence is that Google temporarily rate-limits or blocks your IP for minutes to hours, and jobs return failed or empty results in the meantime. It explicitly says your Google account is not banned. There is no published ban threshold, and the README says so, which means any advice about safe volume is guesswork by design.

The signals it tells you to watch are jobs returning failed, suddenly empty results, or far fewer rows than an identical earlier run. The recommended response is to pause, lower depth, or add proxies. Proxies go in the job body as a proxies array, and the README lists socks5, socks5h, http and https with optional auth, rotating automatically. It also notes that email extraction is much slower and should be switched on only when you need emails.

Two boundaries are firm. First, this is not a social media scraper; the README states it cannot touch Instagram, TikTok or YouTube, and the skill deliberately does not trigger on those requests. Second, the README says scraping Maps is against Google's terms of service and that scraped phones and emails are personal data, so GDPR, CCPA and CAN-SPAM apply if you store or contact them. It tells you to treat results as leads to verify rather than a redistributable dataset, and not to resell raw Google data. If your plan requires redistributing the data or scraping at a volume that needs a proxy pool you do not have, this is the wrong tool.

How it compares with HasData and Omkar Cloud Google Maps Scraper

The alternatives people search for alongside this kit take a different shape. HasData is a hosted scraping API: you send requests to someone else's infrastructure and they handle proxies, browser rendering and blocking. The trade is that your queries and results pass through a third party, you pay per usage, and you cannot inspect the extraction path. The kit does the opposite. It runs gosom/google-maps-scraper on your machine, keeps results in the gmaps_data volume, and asks nothing of a vendor. What you take on instead is the Docker setup, the linux/amd64 emulation on Apple Silicon, and the fact that your own IP is the one Google rate-limits when you overdo it.

Omkar Cloud Google Maps Scraper is another open-source project in the same space, and the meaningful difference is the packaging philosophy rather than the extraction itself. The kit's distinguishing feature is not the scraper, which is upstream's, but the Claude skill and the opinionated output trimming. If you want a library to call from your own Python code, a bare scraper project gives you more room. If you want a local service on port 8080 that a coding agent can drive with a sentence, the kit's skill file and slash commands are the part you cannot easily reproduce by installing upstream alone.

One caveat on the comparison: the README's claim that a chat AI fetching maps.google.com returns almost no structured results is not a benchmark against HasData or Omkar Cloud. It is a claim about naive chat-based fetching. Do not read it as a head-to-head result against the other scrapers.

Maintenance, the pinned image and what the licence status leaves open

The last push to this repository was on 2026-09-07, and the repository is not archived. That is recent activity, though a single push date says nothing about how the project will be maintained going forward.

The upgrade path is deliberately manual. docker-compose.yml pins image: gosom/google-maps-scraper:v1.15.0 and carries a comment saying it is pinned to a known-good release for reproducibility and should be bumped deliberately. That means you will not silently pick up upstream changes, and it also means security fixes and new Google Maps behaviour will not reach you until you edit the tag. When you do bump it, verify the port, the -web and -data-folder flags and the volume paths still match, because the kit's scripts and skill assume the API shape at /api/v1/jobs.

On licensing, be careful. The README credits gosom/google-maps-scraper as MIT, and the kit has its own LICENSE file and a CREDITS.md. But the repository's detected licence is NOASSERTION, which means the licence could not be identified automatically. The README does not state the kit's own licence terms in the text available here, and the compose file only pins the upstream image. If you plan to redistribute the kit, bundle it into a product, or rely on the MIT grant, read LICENSE and CREDITS.md yourself and confirm which terms cover which files. This is not legal advice, and the ambiguity is worth resolving before you build on it.

Editorial conclusion

Adopt it if you want a local lead list of businesses and you already run Docker Desktop and Claude Code, since the compose file pins gosom/google-maps-scraper:v1.15.0 and the scripts need no dependencies. Do not adopt it if you need hosted scraping, social media data, or a redistributable dataset; the kit strips coordinates, IDs, hours and review blobs by default, and the README warns that over-use can get your IP temporarily blocked. Verify first what the LICENSE file actually grants, because the detected licence is NOASSERTION even though the README credits the upstream project as MIT. Then run docker compose up -d, curl http://localhost:8080/api/v1/jobs to confirm the API answers with a JSON list, and start at depth 5 before raising it.

Frequently asked questions

Official sources

1. Issues
2. Mahanaicoach/google-maps-scraper-kit on GitHub
3. README