Google Maps Scraper Kit: a free, open source Google Maps scraper for lead generation with Claude Code

Google Maps Scraper Kit is a free, open source Google Maps scraper that turns a search like "dentists in Austin" into a CSV with each business's name, phone, email, website, category, address, rating and review count. It runs on your own machine with Docker, needs no Google API key and no SaaS credits, and ships a skill so Claude Code, Codex or Cursor can drive it in plain English.

We read the source of v1.1.0 and its engine, ran it for real with two searches in Quito, and in this article cover what it does for small businesses and large companies in any industry, how to install it and, with the same care, what Google's terms and the data protection laws of the US, the EU and Ecuador say about using it.

What Google Maps Scraper Kit is and who builds it

• Repository: github.com/Mahanaicoach/google-maps-scraper-kit
• Version reviewed: v1.1.0 (last commit on October 14, 2026).
• License: MIT, copyright Mahan (@Mahanaicoach). Checked in the LICENSE file, not just the README badge.
• Engine: gosom/google-maps-scraper by Georgios Komninos, also MIT, run as its official, unmodified Docker image v1.18.1.

The kit doesn't reinvent scraping. The gosom engine already does the hard part: it opens Google Maps in a headless browser, walks the results and stores about 34 fields per business. The kit adds the layer that makes it useful for sales:

• A docker-compose.yml that starts the engine on 127.0.0.1:8080, reachable only from your machine.
• scripts/scrape.py, a dependency-free Python CLI that creates the job, waits for it, downloads the CSV and keeps only the 8 contact fields.
• City geocoding through OpenStreetMap, batch searches, a grid mode to get past the ~120 results per search cap, and email and social profile extraction from each business's website.
• A skill and four commands (/scrape, /scrape-batch, /scrape-setup, /scrape-jobs) for Claude Code, with responsible-use guardrails built in.

How it works

A scrape is an asynchronous job against the local REST API:

1. POST /api/v1/jobs with the keywords, latitude and longitude as strings, the scroll depth and the time limit in seconds (max_time). Without lat, lon or max_time the API returns 422.
2. GET /api/v1/jobs/{id} until the Status field goes from working to ok.
3. GET /api/v1/jobs/{id}/download returns the 34-column CSV, and the script keeps title, phone, emails, website, category, address, review_rating and review_count.

Emails come from two passes. The engine visits each business website with email: true, then the script checks up to three contact or about pages for rows that are still empty. Social profiles (--socials) are pulled with regular expressions from the homepage HTML: zero AI tokens, even when Claude drives it.

Benefits for small businesses and large companies

The useful question isn't how many contacts it pulls, but which business decision it saves you time on or improves. We split the use cases by company size because they differ quite a bit.

For small businesses and founders

• A local prospect list in minutes, at no cost. A dental supply distributor, a web agency or a restaurant software vendor gets the list of clinics, practices or venues in their city, with phone and website, in an afternoon. Cloud alternatives charge per result or per month.
• Find businesses missing what you sell. Filter rows without a website and you have businesses that still need a site; filter by low review_count and you have businesses that could use review management.
• Study the competition before you open. How many coffee shops, hardware stores or gyms there are per neighborhood, their average rating and how many reviews they have. It's basic market research that used to be done on foot.
• Find suppliers and partners. Workshops, print shops, carriers or accountants in an area, with ratings so you start with the best.
• Audit your own listing. See how you show up against others in your category: category, reviews and whether your website is linked.

For mid-size and large companies

• Sales territory planning. With --grid and batch searches, a sales team splits territories by the real density of potential customers per city instead of by gut feeling.
• Expansion and site selection. A pharmacy chain, a bank or a food franchise sees where competitors and complementary businesses cluster before opening a new branch.
• CRM enrichment and cleanup. Matching your business customer base against up-to-date public data (phone, website, whether the location is still open) cuts bounces and dead calls.
• Monitoring your retail network. A manufacturer or franchise checks how its dealers and locations appear on Maps: name, category, rating and reviews, to catch badly configured listings.
• Data stays in your infrastructure. Because it runs on your machine or your server, results never pass through an outside vendor, which your security and compliance teams will appreciate.

Examples by industry

How to install it and run your first scrape

You need Docker Desktop. Python 3 is optional and installs nothing extra.

git clone https://github.com/Mahanaicoach/google-maps-scraper-kit.git
cd google-maps-scraper-kit
docker compose up -d
curl http://localhost:8080/api/v1/jobs

If the last command prints [] or null, the engine is ready. The first run pulls the gosom image: 2.06 GB in our test, since it bundles Chromium.

First scrape, with the city geocoded for you:

python3 scripts/scrape.py "dentists in Denver CO" --city "Denver, CO" --depth 5

The whole city, past the ~120 results per search cap, as a deduplicated 3 x 3 grid:

python3 scripts/scrape.py "plumbers in Phoenix AZ" --city "Phoenix, AZ" --grid 3

Several searches in one job, one per line in a file:

python3 scripts/scrape.py --keywords-file my-searches.txt --city "Austin, TX" --socials

On Windows use py scripts/scrape.py. The bash script scrape.sh needs WSL2 or Git Bash.

With Claude Code

Open the kit folder with claude and the skill and commands load automatically. You can also install just the skill into your agent with npx skills add mahanaicoach/google-maps-scraper-kit. Then simply ask:

Make sure the engine is up, search gyms in Miami at depth 5 and give me a table with name, phone and website.

The skill makes the agent save the CSV to disk and show only a few sample rows instead of dumping personal data into the chat. If you're new to skills, start with what Claude Code skills are and how to install them.

What we found when testing it on Windows

We installed and ran it for real on a Windows 11 PC with Docker Desktop 29.2.1 and Python 3.14.3, using kit v1.1.0 and engine v1.18.1. We ran two small searches in Quito, Ecuador (depth 2) to stay well within Google's limits.

What we took away from the test:

• The industry matters more than the tool. Almost no hardware store in Quito has a website, so there's nowhere to find an email: the phone number is the useful field. Dental clinics do have websites, and 41% publish an email. Before planning an email campaign, check how many businesses in your industry have a site.
• The first run downloads 2.06 GB. The engine image bundles Chromium and is much bigger than "a few hundred MB". After that it started in 29 seconds.
• Port 8080 is often taken. On our PC pgAdmin was using it. The fix is the one the kit ships: a .env file with SCRAPER_PORT=8090.
• With no jobs, the API returns null, not []. If you check it with curl, either answer means the engine is ready.
• English categories through the script. scrape.py sends "lang": "en" to the engine. Through the API with "lang": "es" they come back in Spanish, as the table shows.
• Broken accents outside Excel. On Windows the script writes the CSV in the system encoding (cp1252), not UTF-8. Excel opens it fine; Google Sheets and other tools garble accented characters. The raw CSV downloaded from the API is UTF-8.
• The engine's home page shows an empty job table. In v1.18.1 the web UI at localhost:8080 doesn't list jobs even after they finish; they do show up at /jobs and /api/v1/jobs.

We also ran its tests and its extraction functions offline. All 11 of the kit's tests pass, and its contact page discovery has a weak spot outside English.

• Non-English contact pages: partial coverage. The second email pass looks for links containing contact or about. Spanish /contacto matches as a substring, but /nosotros or /quienes-somos don't, and the fallback paths it tries are /contact, /contact-us, /about and /about-us. In our hardware store test that second pass added no emails.
• Free-mail addresses. The extractor ranks emails on the business's own domain first, but also keeps Gmail or Hotmail addresses found on the page. For small businesses that's often the owner's personal address, which makes it personal data (more below).

The legal side, without drama and without shortcuts

The README itself is blunt: scraping Google Maps is against Google's terms, and phones and emails are personal data. That doesn't make every use illegal, but it does mean you have to do it properly. This is general information, not legal advice; for a large campaign, talk to a lawyer in your jurisdiction.

Google's terms

The Google Maps Additional Terms of Service (last modified June 4, 2025) prohibit, as a condition of your license, to "mass download or create bulk feeds of the content" and to use Google Maps to create or augment a "business listings database, mailing list or telemarketing list" for use in a service that substitutes for Google Maps.

In practice the risk is contractual and technical: Google can rate-limit your IP for minutes or hours (the kit warns about this and suggests proxies) or block access. That isn't a crime in itself, but reselling the database or building a directory from it is exactly what those terms target. If your company needs this data continuously and at scale, the clean contractual route is the official Google Places API, which is paid and has its own terms.

European Union (GDPR)

• Company data isn't personal data; a person's data is. A corporation's switchboard number isn't covered, but a sole trader's mobile number and personal email are.
• Lawful basis and transparency. You need a legal basis (usually legitimate interest under Article 6(1)(f), with the balancing test documented) and you must tell people where you got their data (Article 14).
• Two real cases. In Poland, Bisnode was fined over PLN 943,000 for not informing the business owners whose data it took from public registers, and in 2023 the Supreme Administrative Court confirmed that duty existed (UODO). In France, the CNIL fined KASPR €240,000 in December 2024 for collecting LinkedIn contacts without a lawful basis, keeping them too long and informing people late (CNIL). Cold commercial email also has its own rules in each EU country.

United States

The kit points to CAN-SPAM for email (truthful sender, a physical address and a working opt-out) and CCPA in California. For calls and texts to mobile numbers, also check the TCPA, which is strict about automated systems.

Ecuador (LOPDP)

Ecuador's Personal Data Protection Law applies the same logic: Ecuador's data protection authority (SPDP) stated in 2026 that data from publicly accessible sources "does not authorize its free use", and the new purpose must be compatible with the reason it was made public (NMS Law summary). Private companies face fines of 0.1% to 1% of turnover depending on severity (NMS Law summary).

For the full map of US, EU and Ecuador laws that affect software projects, see our guide to the legal risks of AI-built apps.

Responsible use checklist

• Use the data for targeted, verified B2B prospecting, not to resell or publish the database.
• Keep only the 8 fields you need (the kit already drops the rest) and delete what doesn't convert within a set period.
• In your first contact, say who you are, where you got the data and how to opt out. Keep that suppression list.
• No automated mass sends: one relevant message to a specific business, not spam.
• Keep the engine on 127.0.0.1. It has no authentication; exposing it to the internet hands your scraper and your results to anyone.
• One search at a time, depth 5 to start, and proxies only if you really run large jobs.

Common errors

FAQ

Is it free? Yes. The kit and the engine are MIT licensed, with no credits or subscriptions. You only provide your machine and your connection.

Do I need a Google Maps API key? No. The engine drives a headless browser against Google Maps, with no API or billing. That's exactly why Google Maps' end-user terms apply rather than the API terms.

How many businesses per search? About 120, which is Google Maps' cap. --grid 3 splits the city into 9 tiles and removes duplicates.

Does it find every business's email? No. Only for businesses that have a website and publish an email on it. Expect emails on a share of rows, not all of them.

Is scraping Google Maps legal? It breaches Google's terms, which is a contractual risk, not a crime in itself. What the law does regulate is what you do with the personal data you collect: GDPR in Europe, CAN-SPAM, TCPA and CCPA in the US, and the LOPDP in Ecuador.

Can I use it without Claude Code? Yes. scripts/scrape.py runs from any terminal on Windows, macOS and Linux.

Conclusion

Google Maps Scraper Kit gives any company, from a neighborhood hardware store to a national chain, a prospecting and market research tool that used to cost subscriptions or whole afternoons of copy-pasting. It's free, MIT licensed and stays on your machine. Use it to find who to sell to and to understand your market, treat personal data as carefully as your own, and don't turn the results into a database for resale.

For more open source tools that plug into Claude Code, see OpenSEO, the Semrush and Ahrefs alternative.