google-trends

Google Trends

通过 Frevana 查询 Google Trends。

用途

此技能用于获取 Google Trends 结果。

输入：

• q
• 可选的 geo
• 可选的 cat
• 可选的 date
• 可选的 gprop
• 可选的 hl
• 可选的 tz

输出：

• 经过验证且包含 Google Trends 结果的响应 JSON
• 每次成功运行时，都会将相同的已验证 JSON 保存到本地文件

此技能会验证响应是否为 JSON，将其保存到磁盘，并在标准输出上原样返回。除非用户明确要求转换数据，否则不要重写或调整返回的数据结构。

此技能所需内容

• 用户提供的 q
• 可选的 geo
• 可选的 cat
• 可选的 date
• 可选的 gprop
• 可选的 hl
• 可选的 tz
• 环境变量中的 FREVANA_TOKEN，或当前运行时显式指定的 --token 覆盖值
• curl
• bash
• python3

执行顺序

按以下流程执行，让请求保持简单可靠：

1. 确认用户已提供 q 或等效的趋势搜索查询。
2. 优先使用脚本，而不是临时编写 curl 命令。
3. 让脚本首先读取 FREVANA_TOKEN。
4. 在交互式 Shell 中，如果缺少 FREVANA_TOKEN，脚本可以提示用户输入。
5. 在非交互式或 Agent 工作流中，如果缺少令牌，则立即失败，并告知用户设置 FREVANA_TOKEN 或显式传入 --token。
6. 运行一次脚本。脚本会将已验证的 JSON 输出到标准输出，并将相同的 JSON 保存到文件。
7. 后续解析或总结时，使用已保存的 JSON 文件，而不是再次调用 Trends API。
8. 返回已验证的响应 JSON；如果用户不需要完整数据，则总结趋势数据。

命令

基本趋势查询

bash <skill-path>/scripts/search_google_trends.sh \
  --q "home treadmill"

--query 可作为 --q 的别名。

查询地区、日期范围、语言和时区

bash <skill-path>/scripts/search_google_trends.sh \
  --q "home treadmill" \
  --geo US \
  --date "today 12-m" \
  --hl en \
  --tz 420

查询类别和 Google 属性

bash <skill-path>/scripts/search_google_trends.sh \
  --q "running shoes" \
  --cat 18 \
  --gprop images

将响应 JSON 保存到指定文件

bash <skill-path>/scripts/search_google_trends.sh \
  --q "home treadmill" \
  --geo US \
  --output ./out/google-trends-result.json

覆盖当前运行使用的令牌

bash <skill-path>/scripts/search_google_trends.sh \
  --q "home treadmill" \
  --token "your bearer token"

固定请求格式

脚本会发送以下格式的载荷，并省略未提供的可选字段：

{
  "q": "home treadmill",
  "geo": "US",
  "cat": "18",
  "date": "today 12-m",
  "gprop": "images",
  "hl": "en",
  "tz": "420"
}

只有 q 是必填项。用户未提供 geo、cat、date、gprop、hl 或 tz 时，不要自行编造这些值。

响应格式

API 会返回 Frevana JSON。此技能会验证响应是否为 JSON，并原样返回。

输出

• 成功：脚本会验证响应正文是否为 JSON，将其写入文件，在标准错误上打印保存路径，并在标准输出上打印 JSON
• 默认文件路径：./out/google-trends-<UTC timestamp>-<pid>.json
• 使用 --output 时：将相同的 JSON 写入指定文件路径，而不是默认路径
• 失败：脚本会打印响应正文或解析错误，并以非零状态码退出

备注

• 必须提供 --q 或 --query
• 仅当用户要求指定 Trends 的国家/地区代码时，才使用 --geo
• 仅当用户提供类别 ID 时，才使用 --cat
• 仅当用户提供日期范围时，才使用 --date
• 仅当用户要求指定 Google 属性（例如图片、新闻、youtube 或 froogle）时，才使用 --gprop
• 仅当用户要求指定语言代码时，才使用 --hl
• 仅当用户提供以分钟为单位的时区偏移量时，才使用 --tz
• 如果缺少 curl，则停止并告知用户安装 curl
• 如果缺少 python3，则停止并告知用户安装 python3
• 不要向用户回显 Bearer 令牌
• 除非用户要求完整数据，否则应总结用户实际关心的趋势结果，而不是倾倒原始 JSON

示例提示词

中文

• “查询 Google Trends 上 home treadmill 的趋势”
• “查一下 Google Trends 里 q=家庭跑步机，geo=US，date=today 12-m，hl=en”
• “用 Google Trends 看 running shoes 在美国过去 12 个月的趋势，并保存原始 JSON”

英文

• “在 Google Trends 上搜索 home treadmill”
• “查询 Google Trends 中 running shoes 的趋势，geo=US，date=today 12-m”
• “在购物属性中查询 Google Trends 上 coffee maker 的趋势，并保存原始 JSON”