google-maps-search-api-skill

Google Maps 搜索自动化技能

📖 简介

此技能利用 BrowserAct Google Maps Search API 模板，提供一站式商家数据采集服务。它可直接从 Google Maps 搜索列表中提取结构化商家结果。只需提供搜索关键词、语言和国家/地区筛选条件，即可获取整洁、可用的商家数据。

✨ 功能

1. 无幻觉：预设工作流可避免 AI 生成式幻觉，确保数据提取稳定、精准。
2. 无验证码问题：无需处理 reCAPTCHA 或其他验证挑战。
3. 无 IP 限制：无需处理地区 IP 限制或地理围栏。
4. 执行更快：与纯 AI 驱动的浏览器自动化方案相比，任务执行速度更快。
5. 经济高效：与高 Token 消耗的 AI 方案相比，大幅降低数据获取成本。

🔑 API 密钥设置

运行前，检查 BROWSERACT_API_KEY 环境变量。如果未设置，不要采取其他措施；请询问用户并等待其提供。 Agent 必须告知用户：

“由于您尚未配置 BrowserAct API Key，请访问 BrowserAct 控制台 获取您的密钥。”

🛠️ 输入参数

调用脚本时，Agent 应根据用户需求灵活配置以下参数：

1. KeyWords

   • 类型：string
   • 说明：要在 Google Maps 上搜索的内容。可以是商家名称、类别或具体关键词。
   • 示例：coffee shop、dental clinic、coworking space

2. language

   • 类型：string
   • 说明：设置界面语言以及返回文本字段的语言。
   • 常用值：en、de、fr、it、es、ja、zh-CN、zh-TW
   • 默认值：en

3. country

   • 类型：string
   • 说明：设置搜索结果偏向的国家或地区。
   • 示例：us、gb、ca、au、de、fr、jp
   • 默认值：us

4. max_dates

   • 类型：number
   • 说明：从搜索结果列表中提取地点的最大数量。
   • 默认值：100

🚀 使用方法

Agent 应执行以下独立脚本，以实现“一行命令获取结果”：

# Example call
python -u ./scripts/google_maps_search_api.py "search keywords" "language" "country" count

⏳ 执行监控

由于此任务涉及自动化浏览器操作，可能需要一些时间（几分钟）。脚本会持续输出带时间戳的状态日志（例如，[14:30:05] Task Status: running）。 Agent 操作说明：

• 等待脚本结果期间，持续监控终端输出。
• 只要终端持续输出新的状态日志，任务就处于正常运行状态；不要误判为死锁或无响应。
• 只有在状态长时间未变化，或脚本停止输出且未返回结果时，才应考虑触发重试机制。

📊 数据输出

成功执行后，脚本会解析并直接打印 API 响应中的结果。字段包括：

• name：商家名称
• full address：完整地址
• rating：星级评分
• review count：评价数量
• price range：价格级别
• cuisine type：商家类别
• amenity tags：Wi-Fi 等设施标签
• review snippet：评价简述
• service options：服务选项（例如，“在线订购”）

⚠️ 错误处理与重试

如果脚本执行期间发生错误（例如网络波动或任务失败），Agent 应遵循以下逻辑：

1. 检查输出内容：

   • 如果输出包含 "Invalid authorization"，则表示 API Key 无效或已过期。不要重试；引导用户重新检查并提供正确的 API Key。
   • 如果输出不包含 "Invalid authorization"，但任务失败（例如输出以 Error: 开头或返回空结果），Agent 应自动尝试重新执行脚本一次。

2. 重试次数限制：

   • 自动重试仅限一次。如果第二次尝试仍失败，请停止重试，并向用户报告具体错误信息。

🌟 典型用例

1. 本地商家发现：查找曼哈顿的所有“意大利餐厅”。
2. 销售线索挖掘：提取伦敦的“房地产中介”列表，用于寻找潜在客户。
3. 竞争对手分布图：查找某个城市的所有“Starbucks”门店，以绘制竞争分布图。
4. 市场调研：分析巴黎的“精品酒店”，包括其评分和价格区间。
5. 联系信息收集：收集悉尼“牙科诊所”的地址和名称。
6. 服务搜索：查找某个区域的“24 小时药房”或“紧急水管工”。
7. 社区监测：追踪某个社区新开业的“健身房”或“瑜伽工作室”。
8. 结构化数据导出：导出“汽车经销商”的结构化数据，以便与 CRM 集成。
9. 情感分析准备：获取“热门旅游景点”的评论摘要和评分。
10. 全球搜索本地化：使用不同的语言和国家设置，调研全球的“科技中心”。