google-maps-reviews-api-skill

Google Maps 评论自动化技能

📖 简介

这项技能使用 BrowserAct 的 Google Maps Reviews API 模板，提供一站式评论采集服务。它可以直接从 Google Maps 搜索结果中提取结构化评论数据。只需提供搜索关键词、语言和国家/地区，即可获取干净、可用的评论数据。

✨ 功能

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

🔑 API 密钥设置

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

"由于您尚未配置 BrowserAct API Key，请访问 BrowserAct Console 获取您的 Key。"

🛠️ 输入参数

调用脚本时，Agent 应灵活配置以下参数：

1. KeyWords（搜索关键词）

   • 类型：string
   • 说明：用于在 Google Maps 上查找地点的查询词（例如商家名称、类别）。
   • 示例：coffee shop、dental clinic、Tesla showroom

2. language（语言）

   • 类型：string
   • 说明：设置界面语言和返回文本的语言。
   • 支持的值：en、zh-CN、es、fr 等。
   • 默认值：en

3. country（国家/地区）

   • 类型：string
   • 说明：搜索结果偏向的国家或地区。
   • 支持的值：us、gb、ca、au、jp 等。
   • 默认值：us

🚀 使用方法

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

# Example call
python -u ./scripts/google_maps_reviews_api.py "Keywords" "Language" "Country"

⏳ 执行监控

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

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

📊 数据输出

执行成功后，脚本会解析并打印 API 响应中的结果：

• author_name：评论者的显示名称
• author_profile_url：评论者的个人资料 URL
• rating：星级评分
• text：评论文本内容
• comment_date：人类可读的日期
• likes_count：点赞数
• author_image_url：评论者的头像 URL

⚠️ 错误处理与重试

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

1. 检查输出内容：

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

2. 重试次数限制：

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

🌟 典型用例

1. 本地商业分析：查找特定区域内咖啡馆或诊所的评价。
2. 声誉监控：跟踪某个品牌门店的反馈。
3. 竞争对标：分析竞争对手门店的评价。
4. 情感分析：收集评价文本，用于情绪和主题建模。
5. 市场调研：评估不同地区的服务质量。
6. 潜在客户筛选：利用评价数据识别优质服务提供商。
7. 客户洞察：了解反复出现的投诉或好评。
8. 场所调研：收集公园、博物馆或景点的评价。
9. 零售监控：收集新开门店的反馈。
10. 服务质量审计：分析特定连锁服务机构的评分和评论。