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. 対話型シェルで使用する場合、FREVANA_TOKEN が設定されていなければ、スクリプトから入力を求めてもかまいません。
5. 非対話型またはエージェントのワークフローでは、トークンがない場合はすぐに処理を失敗させ、FREVANA_TOKEN を設定するか、--token を明示的に渡すようユーザーに伝えます。
6. スクリプトを一度実行します。検証済み JSON が標準出力に出力され、同じ JSON がファイルに保存されます。
7. 後続の解析や要約には、トレンド API を再度呼び出すのではなく、保存済みの JSON ファイルを使用します。
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 が書き込まれます
• 失敗時：スクリプトはレスポンス本文または解析エラーを表示し、0 以外の終了コードで終了します

注意事項

• --q または --query を必須とします
• ユーザーが Trends の国／地域コードを求めた場合にのみ --geo を使用します
• ユーザーがカテゴリ ID を指定した場合にのみ --cat を使用します
• ユーザーが期間を指定した場合にのみ --date を使用します
• ユーザーが画像、ニュース、YouTube、froogle などの Google プロパティを求めた場合にのみ --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 を検索して」
• 「geo=US、date=today 12-m を指定して、Google Trends で running shoes を調べて」
• 「Google Trends でショッピングプロパティの coffee maker を検索して、生の JSON を保存して」