yaronbeen/bright-data-google-maps-scraper

# Google Maps Scraper (Python) — 通过 Bright Data [](https://github.com/yaronbeen/bright-data-google-maps-scraper/actions/workflows/tests.yml)  [](./LICENSE) -brightgreen) 提取 **Google Maps 商业数据** — 包括名称、地址、电话、网站、评分、评论数、类别和坐标 — 只需一个无依赖的 Python 脚本，由 **[Bright Data](https://brightdata.com)** 维护的 Google Maps 数据集提供支持。仅获取公开数据；无需登录或 cookies。 - **零依赖** — 仅使用 Python 3.8+ 标准库 - **两种输入模式** — 按地点发现商家，或抓取特定的地点 URL - **可选评论** — 获取每个地点的近期评论 (`--reviews`) - **CSV 或 JSON** 输出 (`--format`) - **Dry-run** 模式，用于验证输入和你的 API key，无需消耗额度 ## 快速开始 ``` # 1. 获取 Bright Data API key（免费层级：5,000 条记录/月，无需信用卡）： # https://brightdata.com/cp/setting/users export BRIGHT_DATA_API_KEY="your-key" # 2. 运行内置示例（NYC 咖啡店，LA 牙医，Chicago 水管工） python google_maps_scraper.py # 3. 先验证您自己的文件 — 不消耗 credit： python google_maps_scraper.py locations.csv --dry-run # 4. 正式运行 python google_maps_scraper.py locations.csv # discovery -> output_places.csv python google_maps_scraper.py places.csv out.json --format json python google_maps_scraper.py places.csv --reviews # places + reviews ``` 无需 `pip install`。 ## 命令行参考 ``` python google_maps_scraper.py [input] [output] [options] positional: input Input CSV (locations.csv or places.csv). Omit for built-in sample. output Output file. Default: output_places.csv (or .json) options: --format {csv,json} Output format (default: csv) --reviews Also collect recent reviews for each place (separate dataset) --review-days N How many days of reviews to pull (default: 30) --limit N Max rows to write / review targets to fetch --dry-run Validate input + API key without collecting (spends no credit) --quiet Suppress progress output --version Print version -h, --help Show help ``` ## 输入与输出 ### 输入 A — 发现模式 (`locations.csv`) 按关键字查找地理位置附近的商家。 ``` keyword,lat,long,zoom_level,country coffee shop,40.7484,-73.9857,14,US dentist,34.0522,-118.2437,13,US ``` | 列名 | 必填 | 类型 | 默认值 | 备注 | |--------|----------|------|---------|-------| | `keyword` | 是 | Text | — | 商业搜索词 | | `lat` | 是 | Float | — | 纬度 (-90 到 90) | | `long` | 是 | Float | — | 经度 (-180 到 180) | | `zoom_level` | 否 | Int | 14 | 地图缩放级别，限制在 1–20。数值越大覆盖区域越小 | | `country` | 否 | 2-letter | US | ISO 3166-1 alpha-2 代码 | ### 输入 B — URL 收集 (`places.csv`) ``` url https://www.google.com/maps/place/Empire+State+Building ``` | 列名 | 必填 | 备注 | |--------|----------|-------| | `url` | 是 | 完整的 Google Maps 地点 URL。也支持无表头的纯 URL 文件。 | ### 输出字段 CSV 列名（或 JSON 键名）。CSV 中的缺失值将为空，JSON 中则为 `null`。参见 [`sample_output.csv`](./sample_output.csv) 查看示例。 | 字段 | 类型 | 备注 | |-------|------|-------| | `name` | text | 商业名称 | | `category` | text | 主要类别 | | `rating` | float | 星级评分 0–5（或为 null） | | `reviews_count` | int | 评论数量（或为 null） | | `phone` | text | 电话号码 | | `website` | text | 网站 URL | | `address` | text | 完整街道地址 | | `latitude` / `longitude` | float | 坐标 | | `place_id` | text | Google Maps 地点 ID（用于去重） | | `url` | text | Google Maps 地点 URL | 使用 `--reviews` 参数时，会生成第二个文件 `

_reviews.csv`（或 `.json`），包含： `place_url, reviewer_name, rating, review_text, review_date, likes, reviewer_reviews_count`。 ## 工作原理 该脚本使用 Bright Data 的 Datasets API v3： 1. `POST /datasets/v3/trigger?dataset_id=gd_m8ebnr0q2qlklc02fz`（在发现模式下会添加 `type=discover_new&discover_by=location`） 2. 轮询 `GET /datasets/v3/progress/{snapshot_id}` 直到状态变为 `ready` 3. 下载 `GET /datasets/v3/snapshot/{snapshot_id}?format=json` 评论使用单独的数据集（`gd_luzfs1dn2oa0teb81`，输入为 `{"url": ..., "days_limit": N}`）。字段名称经过防御性映射（例如 `name`/`title`，`rating`/`totalScore`），这样即使数据集 schema 存在细微差异，也不会导致解析失败。 ## 使用场景 - **潜在客户开发** — 建立包含电话和网站等信息的本地商家潜在客户名单，并进一步进行数据补充。 - **本地市场调研** — 按区域衡量竞争对手密度、评分和评论量。 - **竞争对手追踪** — 持续追踪一组地点 URL 的评分和评论变化。 - **AI / RAG 数据集** — 导出地点（和评论）的 JSON 格式数据，用于信息检索或分析。 ## 测试 ``` pip install pytest pytest -m unit # pure helpers, no API key needed (runs in CI) pytest -m e2e # live Bright Data API (requires BRIGHT_DATA_API_KEY, spends a little credit) ``` `e2e` 测试套件是字段映射的真实基准：如果 Bright Data 的实时响应使用了不同的键名，`test_collect_by_url` 会触发明显的报错，从而提醒开发者修复 `parse_place()`。 ## 费用 Bright Data **Web Scraper API** 定价（来源于 [brightdata.com/pricing/web-scraper](https://brightdata.com/pricing/web-scraper)，已在本编写时核对）： | 方案 | 价格 | 备注 | |------|-------|-------| | 免费额度 | **5,000 条记录/月** | 无需信用卡 | | 按量付费 | **$1.5 / 1k 条记录** | 仅对成功交付的记录收费 | | Scale | **$499/月** | 包含 38.4 万条记录，超出部分按 $1.3 / 1k 收费 | 你只需为**成功交付的记录**付费，因此内置的 3 次搜索示例仅需几美分。定价可能会调整，请始终在官方价格页面确认。 ## Bright Data 与 Apify 在 Google Maps 上的对比 — 客观对比 Apify 商店中使用最广泛的 Google Maps 抓取工具是 [`compass/crawler-google-places`](https://apify.com/compass/crawler-google-places)（**52.2 万用户**，4.7★，由 Compass 开发并由 **Apify** 维护）。以下是基于双方官方页面在编写时的直接对比。 | | Bright Data (本仓库) | Apify `compass/crawler-google-places` | |---|---|---| | **维护方** | Bright Data (官方供应商) | Compass (第三方开发者)，由 Apify 维护 | | **基础价格** | **$1.5 / 1k 条记录**（→ $499/月 的 Scale 方案中为 $1.3/1k） | **起步价 $1.5 / 1k 个抓取地点** | | **免费额度** | 5,000 条记录 / 月 | 是 (Apify 免费方案) | | **计费模式** | 按成功交付的记录统一计费；仅对成功结果收费 | 按事件计费；基础指标 = `place-scraped` | | **核心字段** | name, category, rating, reviews_count, phone, website, address, lat/long, place_id, url | 核心字段集相同 | | **邮箱 / 职位 / 销售线索** | 不提供 | 作为**付费扩展**提供 | | **评论** | 独立数据集（需额外调用/计费） | 作为**付费扩展**提供 | | **直接基于 place-ID/URL 的详情** | 包含在每条记录中 | 额外收费（付费扩展） | | **生态系统** | 涵盖 450+ 域名的 Datasets + Scraper APIs | 庞大的 Actor 商店 + Make/Zapier 集成 | **客观结论 — 基础价格基本持平（约 $1.5/1k）。** 这*不是*一个强调“更便宜”的推销。真正的差异在于： - **选择 Bright Data**：如果你希望从**官方维护**的抓取工具中获取简单、可预测的**按记录计费**的核心业务数据，享受“仅对成功付费”的计费模式，且无需叠加各种扩展服务。 - **选择 Apify**：如果你需要**丰富的数据补充**（邮箱、销售线索、职位、评论、图片）或深度的**生态系统集成**，并且你愿意在基础价格之上接受付费扩展，使用由社区构建（Apify 维护）的 Actor。 **决策前请核实：** [brightdata.com/pricing](https://brightdata.com/pricing) · [apify.com/pricing](https://apify.com/pricing)。价格和功能经常变动。 ## 许可证 [MIT](./LICENSE) — 可自由使用、修改和分发。 由 **[Bright Data](https://brightdata.com)** 团队构建。这是一个关于 Bright Data Google Maps Scraper API 的开放且可运行的示例。

标签：API集成, BeEF, Python, 可观测性, 命令控制, 商业信息, 地理数据, 安全规则引擎, 数据采集, 无后门, 爬虫, 逆向工具