uppifyagency/ghostmap
GitHub: uppifyagency/ghostmap
开源的Google Maps数据抓取Chrome插件，提取商业信息至CSV。
Stars: 8 | Forks: 6
# 👻🗺️ Ghost Map Pro
## 🧭 什么是 Ghost Map Pro？
## ✨ 功能说明
您在 Google Maps 上搜索；Ghost Map Pro 会静默捕获结果中的每个商家并构建一个线索表格：
| 输出 | 包含内容 |
|---|---|
| 📊 **`ghost-map-.csv`** | 一份宽泛的、适配 CRM 的线索表 — 包含多达 **49 个结构化列**：名称、电话、网站、**邮箱**、完整地址、评分（小数）、评论数、价格区间、营业时间、类别、纬度/经度、邮政编码、省份、国家、Knowledge-Graph ID、所有者信息、主图、预订链接以及线索质量信号（认领状态、所有者最后更新时间、评论分布）。 |
| 📧 **邮箱发现** | 对于每个有网站的商家，扩展程序会访问其主页以及常见的 `/contact`、`/about`、`/privacy` 页面，并提取真实的商家邮箱 — 同时过滤掉跟踪像素、Cloudflare 混淆的地址以及占位收件箱。 |
| 🇮🇹 **意大利市场专属字段** | 一流的 **Partita IVA (VAT)** 提取功能，带有官方校验和验证、`it_IT` 区域设置、逗号小数处理和复合标签页脚解析 — 这是大多数通用 Google Maps 抓取工具会遗漏的细节。 |
## 🚀 特性
## 📊 输出示例
以下是真实运行 `ristoranti Milano`（米兰餐厅）后获取的部分列（数值已匿名化处理）：
```
name,phone,website,email,rating,reviews,address,partita_iva,category
"Trattoria Esempio","+39 02 1234567","trattoria-esempio.it","info@trattoria-esempio.it",4.6,318,"Via Esempio 8, 20121 Milano MI","01234567890","Restaurant"
"Bar Esempio","+39 02 7654321","bar-esempio.it","ciao@bar-esempio.it",4.4,127,"Corso Esempio 2, 20144 Milano MI","09876543210","Cafe"
```
在 Excel/Sheets 中打开它，或者直接导入到您的 CRM 中并开始外联。
## 📦 安装
## 🖱️ 用法
1. 打开 **google.com/maps** 并运行任意搜索（例如 `hotels Florence`、`idraulici Roma`）。
2. 点击 👻 图标打开 **Ghost Map Pro 侧边栏**。
3. 以适合的模式捕获结果：
- **滚动** — 滚动 Maps 结果列表；随着新商家的不断载入，扩展程序会静默进行捕获。
- **Turbo** — 一键抓取当前已载入的所有结果。
- **区域搜索** — 输入一个城市/区域，让它为您扫描网格。
4. *（可选）* 启用 **邮箱发现** 以获取每个商家的网站并提取其邮箱。
5. 点击 **导出** → 下载 **CSV**（或将其发送到您的 webhook）。完成。
## 🧱 工作原理
```
┌──────────────────────────────────────────────────────────────────┐
│ 🪟 SIDE PANEL (ui/sidepanel.html) │
│ drives the flow · renders progress · exports CSV / webhook │
└──────────────┬─────────────────────────────────────▲──────────────┘
start / stop │ │ results · stats
area search ▼ │
┌──────────────────────────────────────────────────────────────────┐
│ 💾 SERVICE WORKER (background/sw.js · MV3 module) │
│ ├─ job queue + autoscaler ├─ area-search grid sweep │
│ ├─ 📧 email-scraper-v2 └─ 🪝 ExportAPI (CSV + webhook) │
│ └─ uses ▶ FingerprintGenerator · SessionPool · CircuitBreaker │
└───────▲──────────────────────────────────┬────────────────────────┘
│ business records │ parse website HTML
┌───────┴───────────────────────────┐ ┌───▼────────────────────────┐
│ CONTENT SCRIPTS (on Google Maps) │ │ OFFSCREEN (offscreen/) │
│ content/gmb/maps-state-watcher │ │ DOM-parses fetched pages │
│ (MAIN world) reads APP_INIT_STATE│ │ for the EmailExtractor │
│ + captures JSPB during scroll │ └─────────────────────────────┘
│ content/gmb/detail-fetcher │
└────────────────────────────────────┘
```
**Runtime 布局：**
```
manifest.json # MV3
background/
sw.js # service-worker entry
email-scraper-v2.js # website fetch + email discovery
area-search.js # area/grid lead sweep
jobQueue.js · autoscaler ... # scheduling + backpressure
content/gmb/
maps-state-watcher.js # MAIN-world: reads page state + JSPB
detail-fetcher.js · loader.js # per-place enrichment
offscreen/parser.js # off-DOM HTML parsing for emails
lib/
EmailExtractor.js # business-email extraction + filters
partitaIva.js # Italian VAT, checksum-validated
phone-normalizer.js # EU phone normalization (Excel-safe)
FingerprintGenerator.js # coherent browser fingerprints
SessionPool.js · CircuitBreaker.js# anti-detection + backoff
ExportAPI.js # CSV + SSRF-hardened webhook export
ui/sidepanel.html / .js # the panel + state controller
```
## 🛡️ 反检测
抓取 Google Maps 时的主要风险在于请求频率，因此 Ghost Map Pro 被设计得像一个真实的用户：
- **一致的指纹** — `FingerprintGenerator` 保持 User-Agent、Accept-Language q-values 和 client hints 内部一致（没有暴露身份的不匹配项）。
- **Session 池** — 在 service-worker 重启期间轮换并保持 session。
- **熔断机制** — 遇到 `429` / `503` 或 Cloudflare 验证时，它会开启冷却期并退避，而不是继续强行请求。
- **邮箱发现限流** — 在获取商家网站时具有按 worker 计算的失败计数器和步调控制。
即便如此：请以人类操作的频率适度使用。请参阅[负责任地使用](#-privacy--responsible-use)。
## ⚖️ Ghost Map Pro vs Apify vs Outscraper vs 官方 API
| | 👻 **Ghost Map Pro** | 💰 Apify / Outscraper | 🏢 Google Places API |
|---|---|---|---|
| **成本** | 免费且开源 | 按次/按行付费 | 有免费额度，之后按每 1000 次计费 |
| **设置** | 加载未打包的扩展程序 | 账号 + actor / token | 云项目 + 计费 + 密钥 |
| **API key** | ❌ 不需要 | ✅ 平台 token | ✅ 需要计费 API key |
| **邮箱发现** | ✅ 内置 | 💲 通常为付费附加项 | ❌ 不提供 |
| **运行环境** | 您的本地浏览器 | 服务商的云端 | Google 服务器 |
| **数据存储位置** | 保留在您的机器上 | 服务商的云存储 | Google |
| **意大利增值税 (P.IVA)** | ✅ 校验和验证 | ⚠️ 极少支持 | ❌ 无 |
| **开源** | ✅ MIT | ❌ | ❌ |
如果您搜索过 *"google maps scraper github"*、*"apify alternative"* 或 *"free google maps lead extractor"* — 这就是满足需求的本地化、免密钥版本。
## 🔐 隐私与负责任地使用
## ❓ 常见问题
**抓取 Google Maps 合法吗？**
为了 B2B 调研而抓取公开可见的商家信息已被广泛采用，但其合法性取决于您所在的司法管辖区、您如何使用这些数据以及平台的服务条款。Ghost Map Pro 仅读取公开数据并将其保存在本地 — 但合规性（Google 服务条款、GDPR、外联法规）由您自行承担。如有疑问，请咨询律师。
**我需要 Google Maps / Places API key 吗？**
不需要。这正是它的核心所在 — 它直接读取您浏览器中已经加载的数据。
**它在意大利以外的地区有效吗？**
是的。核心字段（名称、电话、网站、邮箱、评分、评论、地址、营业时间、地理位置）是国际通用的。**Partita IVA** 字段是意大利特有的附加功能。
**邮箱是从哪里来的？**
来自每个商家*自己的网站*，而不是来自 Google。如果某个商家没有网站（或者网站上没有邮箱），那么该行就只是没有邮箱数据。
**这会导致我的账号或 IP 被封锁吗？**
请适度抓取。反检测层降低了风险，但高频率、大批量的运行仍可能触发速率限制。保持在人类操作的频率是安全区。
**它在 Chrome 网上应用店上吗？**
没有 — 它是通过从源代码加载未打包的扩展程序来运行的，这保证了它的免费性和可审计性。
## 📄 许可证
[MIT](LICENSE) — 可免费使用、fork 和修改。
**Ghost Map Pro** · 一款免费的 **Google Maps 抓取和线索提取** Chrome 扩展程序
由 [Vlad Vrinceanu](https://www.linkedin.com/in/vladvrinceanu/) 开发 · 由 [Uppify](https://github.com/uppifyagency) 维护
*关键词：google maps scraper · scrape google maps · google maps lead generation · google maps email extractor · google maps data extractor · google business profile scraper · apify / outscraper / octoparse alternative · chrome extension · manifest v3 · no API.*
标签：自定义脚本