Free, open-source Google Maps scraper for lead generation (Python, no API key, no Docker). Exports name, phone, email, website, rating and Instagram/Facebook/LinkedIn/TikTok/YouTube/X links to CSV. 100 places with emails in 44 s; --grid beats Google's 120 cap. MX email check, ad-pixel detection. Skill for Claude Code, Codex and Cursor.
Python agent-skillsb2b-leadsclaude-codeclaude-skillscodex-skillsemail-extractoremail-scrapergoogle-mapsgoogle-maps-extractorgoogle-maps-leadsgoogle-maps-scrapergoogle-maps-scraper-pythongoogle-maps-scrapinggooglemaps-scraperheadless-chromelead-generationlead-scraperno-api-keypythonweb-scraping
docs: canonical MIT license, issue templates, contributing and security policy
Mahan Jafarib4141a2c2bed
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.ymlnew file mode 100644index 0000000..ed6aba4--- /dev/null+++ b/.github/ISSUE_TEMPLATE/bug_report.yml@@ -0,0 +1,27 @@+name: Bug report+description: Something in the kit fails or behaves wrongly.+labels: [bug]+body:+ - type: textarea+ id: what+ attributes:+ label: What happened+ description: What you expected, and what happened instead.+ validations:+ required: true+ - type: textarea+ id: command+ attributes:+ label: Command or prompt+ description: The exact command you ran (or what you asked Claude), and the full error output.+ render: shell+ validations:+ required: true+ - type: input+ id: env+ attributes:+ label: Environment+ description: OS, chip (Intel or Apple Silicon), Docker version, and the scraper image tag.+ placeholder: macOS 15, Apple Silicon, Docker 28.1, gosom/google-maps-scraper:v1.18.1+ validations:+ required: truediff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.ymlnew file mode 100644index 0000000..f86eb80--- /dev/null+++ b/.github/ISSUE_TEMPLATE/config.yml@@ -0,0 +1,5 @@+blank_issues_enabled: false+contact_links:+ - name: Run a scrape yourself+ url: https://github.com/Mahanaicoach/google-maps-scraper-kit#quick-start+ about: This repo is a tool you run on your own machine. Issues are not a scraping request service.diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.ymlnew file mode 100644index 0000000..ef01f42--- /dev/null+++ b/.github/ISSUE_TEMPLATE/feature_request.yml@@ -0,0 +1,11 @@+name: Feature request+description: Suggest an improvement to the kit.+labels: [enhancement]+body:+ - type: textarea+ id: idea+ attributes:+ label: What should the kit do?+ description: Describe the problem it solves for you.+ validations:+ required: truediff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdnew file mode 100644index 0000000..c96ecce--- /dev/null+++ b/CONTRIBUTING.md@@ -0,0 +1,13 @@+# Contributing++Thanks for helping improve the Google Maps Scraper Kit.++- **Bugs:** open an issue with the bug report template. Include the exact command and the full error.+- **Pull requests:** keep them small and focused on one change. Test with a `depth 1` scrape before you+ open the PR.+- **Scripts:** `scripts/scrape.py` uses the Python standard library only. Do not add pip dependencies.+ `scripts/scrape.sh` must run on macOS's default bash 3.2.+- **Scraping engine:** changes to the engine itself belong upstream in+ [gosom/google-maps-scraper](https://github.com/gosom/google-maps-scraper).+- **Data:** never commit scrape output. CSV and result files are git-ignored because they hold+ personal data.diff --git a/LICENSE b/LICENSEindex 8304d65..5c092cb 100644--- a/LICENSE+++ b/LICENSE@@ -2,9 +2,6 @@ MIT LicenseCopyright (c) 2026 Mahan (github.com/Mahanaicoach)-This license covers the Google Maps Scraper Kit. The Google Maps scraping engine-it runs is a separate component under its own MIT license — see CREDITS.md.-Permission is hereby granted, free of charge, to any person obtaining a copyof this software and associated documentation files (the "Software"), to dealin the Software without restriction, including without limitation the rightsdiff --git a/README.md b/README.mdindex 648a62f..d103d20 100644--- a/README.md+++ b/README.md@@ -41,9 +41,11 @@ a precise operating manual for it. Result: dozens to hundreds of verified listin## Quick start-Requires Docker Desktop.+Requires [Docker Desktop](https://www.docker.com/products/docker-desktop). Python 3 is optional (standard library only).```bash+git clone https://github.com/Mahanaicoach/google-maps-scraper-kit.git+cd google-maps-scraper-kitdocker compose up -d```@@ -55,6 +57,17 @@ 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 | [email protected] | example.com | Coffee shop | 100 Congress Ave, Austin, TX | 4.7 | 812 |+| Sample Espresso Bar | +1 512-555-0102 | [email protected] | 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).---@@ -114,9 +127,17 @@ google-maps-scraper-kit/│ ├── commands/ /scrape, /scrape-batch, /scrape-setup, /scrape-jobs│ └── skills/google-maps-scraper/SKILL.md├── CLAUDE.md project instructions for Claude Code+├── CREDITS.md scraping engine attribution and license└── SETUP.md full setup guide```+## Support++Found a bug? [Open an issue](https://github.com/Mahanaicoach/google-maps-scraper-kit/issues/new/choose) with+the command you ran and the error. Issues are for problems with the kit. Run your own scrapes with the+quick start above; requests like "find me hotels in Hamburg" are closed without action.+Contributions: [CONTRIBUTING.md](CONTRIBUTING.md). Security reports: [SECURITY.md](SECURITY.md).+## LicenseBuilt by [Mahan](https://github.com/Mahanaicoach). MIT licensed. Third-party components: [CREDITS.md](CREDITS.md).diff --git a/SECURITY.md b/SECURITY.mdnew file mode 100644index 0000000..5de31b5--- /dev/null+++ b/SECURITY.md@@ -0,0 +1,8 @@+# Security policy++The kit binds the scraper API to `127.0.0.1` because the engine has no built-in authentication.+Do not expose port 8080 to a network without an authenticating proxy in front of it.++To report a vulnerability, use GitHub's private+[security advisory form](https://github.com/Mahanaicoach/google-maps-scraper-kit/security/advisories/new).+Do not open a public issue for security problems.diff --git a/SETUP.md b/SETUP.mdindex a8690e5..fe6a177 100644--- a/SETUP.md+++ b/SETUP.md@@ -35,7 +35,7 @@ If someone shared this folder with you, just `cd` into it:```bashcd google-maps-scraper-kit```-(Or clone it from GitHub if it's hosted: `git clone <repo-url> && cd google-maps-scraper-kit`.)+(Or clone it from GitHub: `git clone https://github.com/Mahanaicoach/google-maps-scraper-kit.git && cd google-maps-scraper-kit`.)Create your local config (optional — defaults work as-is):```bashdiff --git a/assets/social-preview.png b/assets/social-preview.pngnew file mode 100644index 0000000..30ada81Binary files /dev/null and b/assets/social-preview.png differ