Google Ads Keywords Search Volume

Google Ads Keywords Search Volume

Retrieve Google Ads keyword search volume through Frevana.

Purpose

This skill is for checking keyword search volume through Google Ads data.

Inputs:

• keywords
• optional search_partners

Output:

• validated response JSON with Google Ads keyword search-volume data

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

What This Skill Needs

• user-provided keywords
• optional search_partners boolean, defaulting to true
• FREVANA_TOKEN in the environment variables, or an explicit --token override for the current run
• curl
• bash
• python3

Execution Order

Use this flow so the request stays simple and reliable:

1. Confirm the user has provided one or more keywords.
2. If the user does not provide search_partners, default to true. In the user-facing response, explicitly say that this default was used when relevant.
3. Prefer the script over ad hoc curl commands.
4. Let the script read FREVANA_TOKEN first.
5. In interactive shell usage, if FREVANA_TOKEN is missing, the script may prompt for it.
6. 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.
7. Return the validated response JSON, or summarize the highest- and lowest-volume keywords if the user does not need the full payload.
8. The script saves the JSON response to ./out/ by default.

Commands

Default search partners

bash <skill-path>/scripts/search_google_ads_keywords_search_volume.sh \
  --keywords "wireless earbuds,gaming headset"

Exclude search partners

bash <skill-path>/scripts/search_google_ads_keywords_search_volume.sh \
  --keywords "wireless earbuds,gaming headset" \
  --search-partners false

Save response JSON to a specific file

bash <skill-path>/scripts/search_google_ads_keywords_search_volume.sh \
  --keywords "wireless earbuds,gaming headset" \
  --output ./out/google-ads-keywords-search-volume-result.json

Token override for the current run

bash <skill-path>/scripts/search_google_ads_keywords_search_volume.sh \
  --keywords "wireless earbuds,gaming headset" \
  --token "your bearer token"

Fixed Request Shape

The script sends this payload shape:

{
  "keywords": [
    "wireless earbuds",
    "gaming headset"
  ],
  "search_partners": true
}

Default values when not provided:

• search_partners: true

Do not pass unsupported fields. Do not pass API keys, output paths, or request metadata in the payload; Frevana handles server-side details.

Response Shape

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

Output

• Success: the script validates that the response body is JSON and prints it to stdout
• Default file path: ./out/google-ads-keywords-search-volume-<UTC timestamp>-<pid>.json
• With --output: the same JSON is written to the specified file path instead
• Failure: the script prints the response body or parsing error and exits non-zero

Notes

• Require --keywords
• --keywords must be a comma-separated list. Trim whitespace and preserve the user-supplied phrases
• --search-partners accepts true, false, 1, 0, yes, no, on, or off
• If the user does not specify search_partners, default to true
• 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 highest- and lowest-volume keywords, and call out obvious gaps or opportunities when the user is doing keyword research

Example Prompts

中文

• "查一下 wireless earbuds 和 gaming headset 的 Google Ads 搜索量"
• "调用 Google Ads keywords search volume API，并把原始 JSON 存到文件"
• "查 Google Ads 关键词搜索量，不包含 search partners"

English

• "Check Google Ads search volume for wireless earbuds and gaming headset"
• "Get Google Ads keyword search volume and save the raw JSON to a file"
• "Check Google Ads keyword search volume without search partners"