Google Maps Scraper Kit

A free, open-source Google Maps scraper for lead generation that runs on your own machine. Name a business type and a city. Get back an outreach-ready CSV with name, phone, email, website, category, address, rating and review count, plus Instagram, Facebook, LinkedIn, TikTok, YouTube and X links when the site shows them. Add --no-socials to skip those, or --no-website for the businesses that still need a site.

No Google Maps API key, no SaaS credits, no data leaving your computer. One command starts the engine, with or without Docker. Then run it from the terminal, or let Claude Code, Codex or Cursor drive it for you in plain English.

Goal	Start here
🚀 Get a lead list in the next 5 minutes	Quick start
🤖 Let an AI coding agent run the scrape	Use it with Claude Code or any agent
📦 Scrape many keywords or cities in one job	Batch jobs
📋 Know what you get and where it stops	What you get and Honest limits
🏆 Compare it with gosom, omkarcloud, Apify, Outscraper and chat AIs	How it compares and the open-source comparison
🧑‍🍳 Follow a worked recipe for dentists, roofers or restaurants	Guides and recipes

Sponsored by Swiftproxy and SerpApi. Paid placements; details below.

---

Quick start

Requires Python 3.9 or newer and Google Chrome (or Chromium, Edge or Brave). The engine and the scripts use the Python standard library by default. Optional website rendering adds Playwright (setup); the basic crawl needs no pip install. No browser installed? The first start downloads Chrome for Testing once, about 100 MB, checked against a pinned SHA-256.

Open a terminal (macOS: Terminal; Windows: PowerShell) and run these four lines:

git clone https://github.com/Mahanaicoach/google-maps-scraper-kit.git
cd google-maps-scraper-kit
python3 scripts/engine.py start
python3 scripts/scrape.py "coffee shops in Austin TX" 30.2672 -97.7431 --depth 2

Port 8080 taken? Run cp .env.example .env, set SCRAPER_PORT=8081 (any free port) in it, and start again. Then use that port wherever these docs say 8080.

On Windows, type py in place of python3. Stop the engine with python3 scripts/engine.py stop.

Prefer Docker? Replace the third line with docker compose up -d, with Docker Desktop installed and open. If the native engine is running, stop it first (python3 scripts/engine.py stop). The two keep separate job lists, so jobs started in one do not show in the other. The first run builds the engine image, about a minute. It is the same engine on the same port, so every other command stays the same.

Prefer clicking? http://localhost:8080 has a form; each job gives a Leads CSV (the 8 lead fields and socials, junk emails dropped), the full raw CSV or JSON. Already running another copy of the kit on this machine? Set SCRAPER_PORT in .env first (SETUP §6, "second copy").

No coordinates handy? Let the Python CLI geocode the city:

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

Each --depth step loads one more batch of about 20 places: --depth 2 returns about 40, --depth 5 up to about 100, near Google's cap of about 120 per search. Need the whole city? Add --grid 3:

python3 scripts/scrape.py "dentists in Denver CO" --city "Denver, CO" --grid 3

Want every listing, not just a grid's worth? --deep-scan (the ! option: slower) runs the grid, then splits every tile that came back at Google's cap into four sub-tiles one zoom level in, deduped:

python3 scripts/scrape.py "restaurants in Denver CO" --city "Denver, CO" --deep-scan

Example output

results-<short job id>.csv from the first command above (pass --out to name it yourself). Illustrative rows. The file also has six social columns after these eight (see below):

title	phone	emails	website	category	address	review_rating	review_count
Example Roasters	+1 512-555-0101	[email protected]	example.com	Coffee shop	100 Congress Ave, Austin, TX	4.7	312
Sample Espresso Bar	+1 512-555-0102	[email protected]	example.org	Cafe	200 S Lamar Blvd, Austin, TX	4.5	128

review_count works in headless mode; see Honest limits.

--browser-sites enables optional Playwright retries when HTTP finds no emails or social profile links. It renders JavaScript and shares the rendered homepage between both passes. Output adds website_fetch_status: http, rendered, blocked, timeout, budget_exhausted or error. See optional setup.

The social columns instagram, facebook, linkedin, tiktok, youtube and x come after the eight lead fields by default. --no-socials drops them. --tech adds fb_pixel, google_ads_tag, analytics, bing_ads, linkedin_insight, tiktok_pixel, cms, mobile_friendly and intent_score, and sorts the hottest leads first. --verify-emails adds email_host. --full keeps every raw column, including coordinates, place IDs, all categories, the week's opening hours and whether the place is open now.

Full walkthrough, platform notes and troubleshooting: SETUP.md.

---

Sponsored by

Swiftproxy - Residential proxies for Google Maps scraping

90M+ residential IPs across 220+ locations, rotating or static, over HTTP(S) and SOCKS5, so big Google Maps and multi-city jobs keep running. Use code PROXY90 for 10% off. Try Swiftproxy →

---

This is the beginning of the README. Read the rest at the original. Read the full README ↗