google-maps-search-api

该技能旨在帮助用户自动从 Google 地图搜索结果中提取商业数据。当用户要求“查找纽约的咖啡店”、“搜索牙科诊所”或“从 Google 地图中提取业务线索”时，客服人员应主动应用此技能。

# Google Maps Search Automation Skill

## ✨ Platform Compatibility

**✅ Works Powerfully & Reliably On All Major AI Assistants**

| Platform | Status | How to Install |
|----------|--------|----------------|
| **OpenCode** | ✅ Fully Supported | Copy skill folder to `~/.opencode/skills/` |
| **Claude Code** | ✅ Fully Supported | Native skill support |
| **Cursor** | ✅ Fully Supported | Copy to `~/.cursor/skills/` |
| **OpenClaw** | ✅ Fully Supported | Compatible |

**Why Choose BrowserAct Skills?**
- 🚀 Stable & crash-free execution
- ⚡ Fast response times
- 🔧 No configuration headaches
- 📦 Plug & play installation
- 💬 Professional support

## 📖 Introduction
This skill provides a one-stop business data collection service through the BrowserAct Google Maps Search API template. Obtain structured business data with just one command.

## 🔑 API Key Guidance
Before running, check the `BROWSERACT_API_KEY` environment variable. If it is not set, do not take further action; instead, request and wait for the user to provide it.
**The Agent must inform the user**:
> "Since you haven't configured the BrowserAct API Key, please go to the [BrowserAct Console](https://www.browseract.com/reception/integrations) to get your Key and provide it to me in this chat."

## 🛠️ Input Parameters Details
The Agent should flexibly configure the following parameters when calling the script based on user needs:

1. **KeyWords (Search Keywords)**
   - **Type**: `string`
   - **Description**: The keywords the user wants to search for on Google Maps.
   - **Example**: `coffee`, `bakery`, `coworking space`

2. **language (UI Language)**
   - **Type**: `string`
   - **Description**: Sets the UI language and the language of the returned text.
   - **Optional Values**: `en`, `de`, `fr`, `it`, `es`, `ja`, `zh-CN`, `zh-TW`
   - **Default**: `en`

3. **country (Country/Region Bias)**
   - **Type**: `string`
   - **Description**: Sets the country or region bias for search results.
   - **Example**: `us`, `gb`, `ca`, `au`, `de`, `fr`, `es`, `it`, `jp`
   - **Default**: `us`

4. **max_dates (Maximum extraction limit)**
   - **Type**: `number`
   - **Description**: The maximum number of places to extract from search results.
   - **Default**: `100`

## 🚀 Execution Method (Recommended)
The Agent should implement "one command for results" by executing the following independent script:

```bash
# Call example
python ./scripts/google_maps_search_api.py "KeyWords" "language" "country" max_dates
```

## 📊 Data Output Description
After successful execution, the script will directly parse and print the results from the API response. Results include:
- `name`: Business name
- `full address`: Business address
- `rating`: Average star rating
- `review count`: Number of reviews
- `price range`: Price level
- `cuisine type`: Business category
- `amenity tags`: Features like Wi-Fi, outdoor seating
- `review snippet`: Highlighted short review
- `service options`: Such as "Order online", "Dine-in"

## ⚠️ Error Handling & Retry
During script execution, if an error occurs (such as network fluctuations or task failure), the Agent should follow this logic:

1. **Check output content**:
   - If the output **contains** `"Invalid authorization"`, the API Key is invalid or expired. **Do not retry**; instead, guide the user to check and provide the correct API Key.
   - If the output **does not contain** `"Invalid authorization"` but the task execution fails (e.g., output starts with `Error:` or returns an empty result), the Agent should **automatically attempt to re-execute** the script once.

2. **Retry Limit**:
   - Automatic retry is limited to **once**. If the second attempt still fails, stop retrying and report the specific error message to the user.

---

## 中文说明

# Google 地图搜索自动化技能

## ✨ 平台兼容性

**✅ 在所有主流 AI 助手上强劲且稳定地运行**

| 平台 | 状态 | 如何安装 |
|----------|--------|----------------|
| **OpenCode** | ✅ 完全支持 | 将技能文件夹复制到 `~/.opencode/skills/` |
| **Claude Code** | ✅ 完全支持 | 原生支持技能 |
| **Cursor** | ✅ 完全支持 | 复制到 `~/.cursor/skills/` |
| **OpenClaw** | ✅ 完全支持 | 兼容 |

**为什么选择 BrowserAct 技能？**
- 🚀 稳定且无崩溃的执行
- ⚡ 快速的响应时间
- 🔧 无配置烦恼
- 📦 即插即用的安装
- 💬 专业支持

## 📖 简介
此技能通过 BrowserAct Google Maps Search API 模板提供一站式商业数据采集服务。只需一条命令即可获取结构化的商业数据。

## 🔑 API Key 指南
运行前，请检查 `BROWSERACT_API_KEY` 环境变量。如果未设置，请勿采取进一步操作；而应请求并等待用户提供它。
**代理必须告知用户**：
> “由于您尚未配置 BrowserAct API Key，请前往 [BrowserAct Console](https://www.browseract.com/reception/integrations) 获取您的 Key，并在此对话中提供给我。”

## 🛠️ 输入参数详情
代理应根据用户需求，在调用脚本时灵活配置以下参数：

1. **KeyWords（搜索关键词）**
   - **类型**：`string`
   - **说明**：用户想要在 Google 地图上搜索的关键词。
   - **示例**：`coffee`、`bakery`、`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`、`es`、`it`、`jp`
   - **默认值**：`us`

4. **max_dates（最大提取上限）**
   - **类型**：`number`
   - **说明**：从搜索结果中提取的地点的最大数量。
   - **默认值**：`100`

## 🚀 执行方法（推荐）
代理应通过执行以下独立脚本来实现“一条命令出结果”：

```bash
# Call example
python ./scripts/google_maps_search_api.py "KeyWords" "language" "country" max_dates
```

## 📊 数据输出说明
成功执行后，脚本将直接解析并打印 API 响应中的结果。结果包括：
- `name`：商业名称
- `full address`：商业地址
- `rating`：平均星级评分
- `review count`：评论数量
- `price range`：价格水平
- `cuisine type`：商业类别
- `amenity tags`：诸如 Wi-Fi、户外座位等特色
- `review snippet`：高亮显示的简短评论
- `service options`：例如“在线下单”、“堂食”

## ⚠️ 错误处理与重试
在脚本执行过程中，如果发生错误（例如网络波动或任务失败），代理应遵循以下逻辑：

1. **检查输出内容**：
   - 如果输出 **包含** `"Invalid authorization"`，则 API Key 无效或已过期。**请勿重试**；而应引导用户检查并提供正确的 API Key。
   - 如果输出 **不包含** `"Invalid authorization"` 但任务执行失败（例如输出以 `Error:` 开头或返回空结果），代理应 **自动尝试重新执行** 脚本一次。

2. **重试限制**：
   - 自动重试仅限 **一次**。如果第二次尝试仍然失败，则停止重试，并向用户报告具体的错误信息。