AIBit-探索开源项目 AIBit-探索开源项目

Google 地图抓取器：大规模开源潜在客户提取

探索一款基于 Go 的 Google 地图抓取器，支持 CLI、Web UI、REST API、代理、邮箱提取和分布式扩展。

Google 地图抓取器：大规模开源潜在客户提取

收集结构化的本地商家数据对于销售获客、市场调研、本地 SEO、数据 enriquecement 和自动化都很有用，但手动从 Google 地图复制商家信息无法扩展。开源项目 gosom/google-maps-scraper 可将 Google 地图搜索结果转换为结构化记录，其中包含商家详情、联系信息、评价、坐标以及可选的电子邮件地址。

该项目采用 MIT 许可证，提供多种运行方式：命令行界面、本地 Web UI、REST API、可选的自托管 SaaS 版本，以及用于自然语言工作流的 AI 智能体技能。项目主要使用 Go 编写，并通过 Playwright 进行基于浏览器的数据提取。

抓取器收集的数据

典型结果可包含超过 33 个字段，包括：

  • 商家名称、类别、描述和营业状态
  • 街道地址和完整格式化地址
  • 电话号码和官方网站
  • Google 地图链接、Place ID、CID 及其他标识符
  • 平均评分、评价数量、评分分布和客户评价
  • 纬度、经度、时区、加号代码和街景 URL
  • 营业时间和热门时段信息
  • 价格区间、预订、菜单和在线订购链接
  • 图片、缩略图、店主状态、接受的信用卡和其他元数据
  • 通过可选抓取商家网站发现的电子邮件地址

使用 -extra-reviews 标志可以扩展评价收集，每个地点最多可获取约 300 条评价。电子邮件提取默认关闭，因为访问每个商家网站会显著增加运行时间。

使用 Docker 快速开始

推荐使用 Docker 安装，因为镜像已包含浏览器自动化环境。创建输出目录，并挂载一个包含每行一个查询的输入文件：

mkdir -p gmaps-output

docker run \\
  -v gmaps-playwright-cache:/opt \\
  -v "$PWD/example-queries.txt:/queries.txt:ro" \\
  -v "$PWD/gmaps-output:/out" \\
  gosom/google-maps-scraper \\
  -input /queries.txt \\
  -results /out/results.csv \\
  -depth 1 \\
  -exit-on-inactivity 3m

查询文件可能如下所示：

柏林的餐厅
奥斯汀的软件公司
雅典的咖啡店

默认输出格式为 CSV。若要改为输出 JSON，请添加 -json 并使用 .json 结果路径：

docker run \\
  -v gmaps-playwright-cache:/opt \\
  -v "$PWD/queries.txt:/queries.txt:ro" \\
  -v "$PWD/output:/out" \\
  gosom/google-maps-scraper \\
  -input /queries.txt \\
  -results /out/results.json \\
  -json \\
  -depth 1 \\
  -exit-on-inactivity 3m

首次运行可能会下载浏览器库并初始化 Playwright 缓存。将 /opt 持久化到命名 Docker 卷中，可以避免重复执行这些操作。

三种使用方式

1. 命令行

CLI 适合可重复执行的任务、Shell 脚本、Cron 任务和数据管道。重要选项包括：

选项 用途
-input 包含查询或 Google 地图 URL 的输入文件
-results CSV、JSON 或 JSONL 输出路径
-depth 最大结果滚动深度；默认为 10
-c 并发抓取任务数量；默认为 CPU 核心数的一半
-email 抓取商家网站中的电子邮件地址
-extra-reviews 收集扩展评价数据
-resume 继续被中断的基于文件的抓取任务
-fast-mode 快速收集每个查询最多 21 条结果
-lang Google 地图语言，例如 de
-geo 搜索坐标，例如 37.7749,-122.4194
-radius 搜索半径，单位为米
-grid-bbox 将地理边界框划分为网格单元

2. Web UI 和 REST API

使用以下命令启动本地 Web UI：

mkdir -p gmapsdata

docker run \\
  -v "$PWD/gmapsdata:/gmapsdata" \\
  -p 8080:8080 \\
  gosom/google-maps-scraper \\
  -data-folder /gmapsdata

打开 http://localhost:8080。服务器还会在 http://localhost:8080/api/docs 提供 OpenAPI 3.0.3 规范。

主要 API 端点包括：

  • POST /api/v1/jobs — 创建抓取任务
  • GET /api/v1/jobs — 列出任务
  • GET /api/v1/jobs/{id} — 查看任务
  • DELETE /api/v1/jobs/{id} — 删除任务
  • GET /api/v1/jobs/{id}/download — 下载 CSV 结果

这使抓取器适合与内部仪表板、CRM 工作流或定时潜在客户生成服务集成。

3. AI 智能体工作流

仓库包含一个 Agent Skills 软件包，可与 Claude Code、Codex、Cursor 和 GitHub Copilot 等工具配合使用。安装命令如下：

npx skills add gosom/google-maps-scraper

然后，你可以提出类似以下请求：

查找柏林的牙医，并包括他们的网站和电子邮件地址。

该技能可以推断搜索默认值、执行小规模验证运行、启动 Docker 抓取、监控进度，并帮助保存或分析结果。代理凭据通过本地终端中的掩码提示输入，而不是粘贴到智能体对话中。在 macOS、Linux 或通过 WSL 运行的 Windows 上，都需要 Docker 和 Node.js。

处理大型任务

在 -c 8 -depth 1 配置下，项目报告的速度约为每分钟 120 个地点，但实际吞吐量取决于查询复杂度、浏览器资源、网络状况和拦截情况。

一个具有代表性的估算如下：

关键词数量 每个关键词的结果数 地点总数 预计时间
100 16 1,600 约 13 分钟
1,000 16 16,000 约 2.5 小时
10,000 16 160,000 约 22 小时

并发数控制同时运行的任务数量。浏览器进程和页面设置提供了额外控制：

./google-maps-scraper \\
  -c 8 \\
  -browser-pool-size 2 \\
  -pages-per-browser 4 \\
  -input queries.txt \\
  -results results.csv \\
  -depth 1

在此配置中，8 个任务分配到 2 个浏览器进程中，每个浏览器打开 4 个标签页。使用 htop 或 docker stats 监控资源使用情况；Chromium 可能消耗大量 CPU 和内存。browser-pool-size 与 pages-per-browser 的乘积应大致等于或大于 -c，以保持工作线程繁忙。

对于被中断的任务，可使用恢复模式：

./google-maps-scraper \\
  -resume \\
  -input queries.txt \\
  -results results.csv \\
  -depth 10

恢复模式会读取已有的 CSV 或 JSONL 输出，跳过已经写入的地点，并维护一个包含已完成输入查询的 <results>.resume.json 旁车文件。该模式要求输出为普通文件，且不能与 stdout、自定义写入器、LeadsDB 输出和快速模式结合使用。

使用网格抓取扩大地理覆盖范围

单次 Google 地图搜索可能无法为高密度区域提供足够结果。网格抓取会将边界框划分为多个单元，并从每个单元执行查询：

./google-maps-scraper \\
  -input queries.txt \\
  -results peristeri-cafes.csv \\
  -grid-bbox "38.0077,23.6719,38.0257,23.6947" \\
  -grid-cell 0.5 \\
  -zoom 16 \\
  -depth 1 \\
  -c 4

网格模式有助于扩大地理覆盖范围，但不会严格将结果限制在边界框内。若要严格进行距离过滤，可在快速模式下使用 -geo 和 -radius，或根据纬度和经度对记录进行后处理。

快速模式每个查询最多返回 21 条按距离排序的结果：

./google-maps-scraper \\
  -input queries.txt \\
  -results results.csv \\
  -fast-mode \\
  -zoom 15 \\
  -radius 5000 \\
  -geo '37.7749,-122.4194'

快速模式目前处于测试阶段，可能更容易受到拦截。它不能与 -grid-bbox 结合使用。

代理配置

对于大型任务，代理可以帮助分散流量并降低速率限制。支持的协议包括 SOCKS5、SOCKS5H、HTTP 和 HTTPS：

./google-maps-scraper \\
  -input queries.txt \\
  -results results.csv \\
  -proxies 'socks5://user:pass@host:port,http://host2:port2' \\
  -depth 1 \\
  -c 2

也可以将每个代理 URL 单独放在文件的一行中：

./google-maps-scraper \\
  -input queries.txt \\
  -results results.csv \\
  -proxies-file proxies.txt

使用代理不能替代负责任的抓取设计。请从低并发开始，先验证小规模样本，并遵守适用法律以及管理所访问数据的相关条款。

直接导出到 LeadsDB

无需写入中间文件，抓取器可以直接将记录发送到 LeadsDB。LeadsDB 提供去重、过滤、API 访问和导出功能：

export LEADSDB_API_KEY="your-api-key"
./google-maps-scraper \\
  -input queries.txt \\
  -exit-on-inactivity 3m

也可以使用 -leadsdb-api-key 显式提供密钥。Google 地图字段会映射到潜在客户字段，例如名称、类别、电话、网站、地址、坐标、评分、评价数量、电子邮件、Logo URL 和来源 ID。其他地图元数据会作为自定义属性保留。

使用 PostgreSQL 和 Kubernetes 扩展规模

对于分布式工作负载，PostgreSQL 可以作为共享任务提供器。在多台机器上启动开发数据库、写入任务并运行抓取器工作线程：

docker-compose -f docker-compose.dev.yaml up -d

./google-maps-scraper \\
  -dsn "postgres://postgres:postgres@localhost:5432/postgres" \\
  -produce \\
  -input example-queries.txt \\
  -lang en

./google-maps-scraper \\
  -c 2 \\
  -depth 1 \\
  -dsn "postgres://postgres:postgres@localhost:5432/postgres"

Kubernetes 部署可以运行多个副本：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: google-maps-scraper
spec:
  replicas: 3
  selector:
    matchLabels:
      app: google-maps-scraper
  template:
    metadata:
      labels:
        app: google-maps-scraper
    spec:
      containers:
        - name: google-maps-scraper
          image: gosom/google-maps-scraper:latest
          args: ["-c", "1", "-depth", "10", "-dsn", "postgres://user:pass@host:5432/db"]
          resources:
            requests:
              memory: "512Mi"
              cpu: "500m"

无头浏览器需要充足的 CPU 和内存分配，因此资源请求应通过负载测试进行调整，而不是盲目照搬。

从源代码构建

项目要求 Go 1.26.6 或更高版本：

git clone https://github.com/gosom/google-maps-scraper.git
cd google-maps-scraper
go mod download
go build
./google-maps-scraper \\
  -input example-queries.txt \\
  -results results.csv \\
  -exit-on-inactivity 3m

开发者还可以创建自定义 Go 写入器插件：

go build -buildmode=plugin -tags=plugin -o myplugin.so myplugin.go
./google-maps-scraper \\
  -writer ~/plugins:MyWriter \\
  -input queries.txt

运行注意事项

匿名遥测默认启用，可通过以下方式关闭：

export DISABLE_TELEMETRY=1

该仓库采用 MIT 许可证，但用户仍需负责遵守适用的隐私、数据保护和网站条款。避免收集不必要的数据，保护导出的联系信息，并在生产工作流中加入速率限制和重试策略。

凭借基于浏览器的数据提取、结构化输出、可恢复任务、地理控制、代理支持、API 和分布式执行等能力，Google Maps Scraper 不只是一次性命令。对于需要将本地搜索结果转化为可重复、可检查数据管道的开发者而言，它是一个实用的基础工具。

来源

gosom/google-maps-scraper：从 Google 地图抓取数据。提取每个地点的名称、地址、电话号码、网站 URL、评分、评价数量、纬度和经度、评价、电子邮件等信息