Amazon Keyword Search Volume

Retrieve Amazon keyword search volume through Frevana.

Purpose

This skill is for checking Amazon keyword demand.

Inputs:

• keywords
• optional location_code
• optional location_name
• optional language_code
• optional language_name

Output:

• validated response JSON with Amazon 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 locationcode, locationname, languagecode, languagename
• 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 location or language, default to United States / English. In the user-facing response, explicitly say that this default was used.
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. When useful, also save the JSON to a file.

Commands

Default marketplace

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

Explicit marketplace

bash <skill-path>/scripts/get_search_volume.sh \
  --keywords "wireless earbuds,gaming headset" \
  --location-name "United States"

Save response JSON to a file

bash <skill-path>/scripts/get_search_volume.sh \
  --keywords "wireless earbuds,gaming headset" \
  --location-name "Germany" \
  --output ./out/amazon-keyword-search-volume-result.json

Token override for the current run

bash <skill-path>/scripts/get_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"
  ],
  "location_code": 2840,
  "location_name": "United States",
  "language_code": "en",
  "language_name": "English"
}

Default values when not provided:

• location_code: 2840
• location_name: United States
• language_code: en
• language_name: English

Supported Marketplaces

Use only these location/language pairs for this skill:

If the user asks for a marketplace outside this list, stop and say that the skill currently supports only the listed marketplaces.

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
• With --output: the same JSON is also written to the specified file path
• 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
• If the user does not specify marketplace/language, default to United States / English
• In the response, state the default explicitly when it was used
• 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 的 Amazon 搜索量"
• "帮我查 Germany 的 Amazon 关键词搜索量"
• "调用 Amazon keyword search volume API，并把原始 JSON 存到文件"

English

• "Check Amazon search volume for wireless earbuds and gaming headset"
• "Get Amazon keyword search volume in Germany"
• "Check Amazon keyword search volume for these terms and save the raw JSON to a file"