Skip to content

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.

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.yml
new file mode 100644
index 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: true
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 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.yml
new file mode 100644
index 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: true
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 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/LICENSE
index 8304d65..5c092cb 100644
--- a/LICENSE
+++ b/LICENSE
@@ -2,9 +2,6 @@ MIT License
Copyright (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 copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
diff --git a/README.md b/README.md
index 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-kit
docker 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).
+
## License
Built by [Mahan](https://github.com/Mahanaicoach). MIT licensed. Third-party components: [CREDITS.md](CREDITS.md).
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 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.md
index a8690e5..fe6a177 100644
--- a/SETUP.md
+++ b/SETUP.md
@@ -35,7 +35,7 @@ If someone shared this folder with you, just `cd` into it:
```bash
cd 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):
```bash
diff --git a/assets/social-preview.png b/assets/social-preview.png
new file mode 100644
index 0000000..30ada81
Binary files /dev/null and b/assets/social-preview.png differ