google-trends

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Google Trends

Query Google Trends through Frevana.

通过Frevana查询Google Trends。

Purpose

用途

This skill is for retrieving Google Trends results.

Inputs:

```
q
```
optional
```
geo
```
optional
```
cat
```
optional
```
date
```
optional
```
gprop
```
optional
```
hl
```
optional
```
tz
```

Output:

validated response JSON with Google Trends results
the same validated JSON saved to a local file on every successful run

This skill validates that the response is JSON, saves it to disk, and returns it unchanged on stdout. Do not rewrite or reshape the returned data unless the user explicitly asks for a transformation.

此Skill用于获取Google Trends结果。

输入参数：

```
q
```
可选参数
```
geo
```
可选参数
```
cat
```
可选参数
```
date
```
可选参数
```
gprop
```
可选参数
```
hl
```
可选参数
```
tz
```

输出：

包含Google Trends结果的验证后响应JSON
每次运行成功后，会将相同的验证后JSON保存到本地文件

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

What This Skill Needs

所需条件

user-provided
```
q
```
optional
```
geo
```
optional
```
cat
```
optional
```
date
```
optional
```
gprop
```
optional
```
hl
```
optional
```
tz
```
```
FREVANA_TOKEN
```
in the environment variables, or an explicit
```
--token
```
override for the current run
```
curl
```
```
bash
```
```
python3
```

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

Execution Order

执行流程

Use this flow so the request stays simple and reliable:

Confirm the user has provided
```
q
```
or an equivalent trend search query.
Prefer the script over ad hoc
```
curl
```
commands.
Let the script read
```
FREVANA_TOKEN
```
first.
In interactive shell usage, if
```
FREVANA_TOKEN
```
is missing, the script may prompt for it.
In non-interactive or agent workflows, fail fast if the token is missing and tell the user to set
```
FREVANA_TOKEN
```
or pass
```
--token
```
explicitly.
Run the script once. It prints the validated JSON to stdout and saves the same JSON to a file.
Use the saved JSON file for any follow-up parsing or summarization instead of calling the trends API again.
Return the validated response JSON, or summarize the trend data if the user does not need the full payload.

遵循以下流程可确保请求简单可靠：

确认用户已提供
```
q
```
或等效的趋势搜索查询。
优先使用脚本而非临时
```
curl
```
命令。
让脚本优先读取
```
FREVANA_TOKEN
```
。
在交互式Shell使用场景中，如果缺少
```
FREVANA_TOKEN
```
，脚本可能会提示用户输入。
在非交互式或Agent工作流中，如果缺少令牌则立即失败，并告知用户设置
```
FREVANA_TOKEN
```
或显式传递
```
--token
```
。
运行一次脚本。它会将验证后的JSON打印到标准输出，并将相同的JSON保存到文件。
后续的解析或汇总操作使用保存的JSON文件，而非再次调用趋势API。
返回验证后的响应JSON；如果用户不需要完整负载，则对趋势数据进行汇总。

Commands

命令示例

Basic trends query

基础趋势查询

bash

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

--query

is accepted as an alias for

--q

bash

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

--query

可作为

--q

的别名使用。

Query with region, date range, language, and timezone

指定区域、日期范围、语言及时区的查询

bash

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

bash

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

Query with category and Google property

指定类别和Google属性的查询

bash

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

bash

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

Save response JSON to a specific file

将响应JSON保存到指定文件

bash

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

bash

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

Token override for the current run

当前运行时覆盖令牌

bash

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

bash

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

Fixed Request Shape

固定请求格式

The script sends this payload shape, omitting optional fields that were not provided:

json

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

Only

is required. Do not invent

geo

cat

date

gprop

hl

, or

tz

values when the user did not provide them.

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

json

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

仅

为必填项。当用户未提供

geo

、

cat

、

date

、

gprop

、

hl

或

tz

时，请勿自行生成这些值。

Response Shape

响应格式

The API returns Frevana JSON. This skill validates the response as JSON and returns it unchanged.

API返回Frevana格式的JSON。此Skill会验证响应为JSON格式，并原样返回。

Output

输出说明

Success: the script validates that the response body is JSON, writes it to a file, prints the saved path to stderr, and prints the JSON to stdout

Default file path:

./out/google-trends-<UTC timestamp>-<pid>.json

With
```
--output
```
: the same JSON is written to the specified file path instead of the default path
Failure: the script prints the response body or parsing error and exits non-zero

成功：脚本验证响应体为JSON格式，将其写入文件，在标准错误输出中打印保存路径，并在标准输出中打印该JSON内容

默认文件路径：

./out/google-trends-<UTC timestamp>-<pid>.json

使用
```
--output
```
参数：将相同的JSON写入指定路径，而非默认路径
失败：脚本打印响应体或解析错误，并以非零状态退出

Notes

注意事项

Require
```
--q
```
or
```
--query
```
Use
```
--geo
```
only when the user requests a country/region code for Trends
Use
```
--cat
```
only when the user provides a category id
Use
```
--date
```
only when the user provides a date range
Use
```
--gprop
```
only when the user requests a Google property such as images, news, youtube, or froogle
Use
```
--hl
```
only when the user requests a language code
Use
```
--tz
```
only when the user provides a timezone offset in minutes
If
```
curl
```
is missing, stop and tell the user to install
```
curl
```
If
```
python3
```
is missing, stop and tell the user to install
```
python3
```
Do not echo the Bearer token back to the user
Summarize the trend results the user actually cares about instead of dumping raw JSON unless they ask for the full payload

必须提供
```
--q
```
或
```
--query
```
仅当用户请求趋势数据的国家/地区代码时才使用
```
--geo
```
仅当用户提供类别ID时才使用
```
--cat
```
仅当用户提供日期范围时才使用
```
--date
```
仅当用户请求Google属性（如images、news、youtube或froogle）时才使用
```
--gprop
```
仅当用户请求语言代码时才使用
```
--hl
```
仅当用户提供分钟级时区偏移量时才使用
```
--tz
```
如果缺少
```
curl
```
，请停止操作并告知用户安装
```
curl
```
如果缺少
```
python3
```
，请停止操作并告知用户安装
```
python3
```
请勿向用户回显Bearer令牌
除非用户要求完整负载，否则应汇总用户实际关心的趋势结果，而非直接输出原始JSON

Example Prompts

示例提示词

中文

"查询 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 里 q=家庭跑步机，geo=US，date=today 12-m，hl=en"
"用 Google Trends 看 running shoes 在美国过去 12 个月的趋势，并保存原始 JSON"

English

中文翻译版

"Search Google Trends for home treadmill"
"Look up Google Trends for running shoes with geo=US and date=today 12-m"
"Query Google Trends for coffee maker in the shopping property and save the raw JSON"

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