This skill queries the historical exact search volume for Amazon keywords via the Jungle Scout data source, returning weekly search volume data points over a specified date range across 10 Amazon marketplaces.
Core Concepts
The Jungle Scout keyword historical search volume tool provides Amazon marketplace keywordweekly exact-match search volumehistorical data. Sellers can determine the following by querying search volume changes within a specified time range:
- Seasonality patterns: which months are peak/off seasons for the keyword
- Trend direction: whether search volume is continuously rising, falling, or stable
- Fluctuation range: determine the stability of market demand
- Holiday effects: search volume spikes around major promotions and holidays
Data granularity: each record represents one 7-day cycle, containing the estimated exact-match search volume for that week.
Data Fields
Output Fields
| Field | API Name | Description | Example |
|---|---|---|---|
| Cycle identifier | id | Data cycle identifier (marketplace/keyword/date range) | us_sushi_20250105_20250111 |
| Cycle start date | estimateStartDate | Start of the 7-day statistical cycle | 2025-01-05 |
| Cycle end date | estimateEndDate | End of the 7-day statistical cycle | 2025-01-11 |
| Exact search volume | estimatedExactSearchVolume | Exact-match search volume within the cycle (times/week) | 12500 |
| Resource type | type | Fixed value | historical_keyword_search_volume |
| Tokens consumed | costToken | Number of tokens consumed by this call | 1 |
Supported Marketplaces
| Marketplace | marketplace value | Description |
|---|---|---|
| United States | us | Amazon.com |
| United Kingdom | uk | Amazon.co.uk |
| Germany | de | Amazon.de |
| India | in | Amazon.in |
| Canada | ca | Amazon.ca |
| France | fr | Amazon.fr |
| Italy | it | Amazon.it |
| Spain | es | Amazon.es |
| Mexico | mx | Amazon.com.mx |
| Japan | jp | Amazon.co.jp |
The default marketplace is us. When the user does not specify a marketplace, use us.
How to call
- API endpoint：
POST /tool-jungle-scout/keywords/historical-search-volume(for complete parameters/responses/error codes, seereferences/api.md） - Python script：
python scripts/junglescout_keyword_history.py '<JSON 参数>' [--inline] - Cost constraints: This tool consumes compute; by default, the same parameter combination in the same session is called only once, and the script has a 24h local cache. On failure/empty results, do not automatically switch keywords, paginate, or change postal codes to probe continuously; if further retrieval is needed, first explain to the user that additional consumption will be incurred.
Output strategy (script default behavior)：
- Alwayswrite the complete response to
<cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-junglescout-keyword-history-<timestamp>.json（<cwd>is the working directory when the script is executed, which in Claude Code is the current project directory;<session>is taken from the environment variableSESSION_ID, automatically aggregated according to the user task;writing to /tmp is prohibited, and an error is reported if the current directory is not writable) - Response body ≤ 8 KB: after writing to disk, print the complete JSON to stdout
- Response body > 8 KB: after writing to disk, stdout outputs only a summary (top-level fields, common counts such as
total/costToken, length of the largest list field + first 3 samples) - Add
--inlineForce full output to stdout (also written to disk)
Data reading recommendations: First check the summary to determine if it is sufficient; when specific fields are needed, prefer using jqorConvertFrom-Json to extract on demand from the saved json file, avoiding bringing the entire JSON into the context.
Resolve authentication and compute capacity issues
When the following abnormal situations occur, use references/onboarding.md to guide resolving the issue:
Abnormal situations
- API Key not configured: Environment variable not configured
LINKFOX_AGENT_API_KEY, and also not configuredLINKFOXAGENT_API_KEY。 - Response returns 401 or 402 status code
- Response indicates insufficient compute capacity or balance: The message contains "insufficient compute balance/insufficient billing/insufficient balance/quota exceeded/insufficient balance/package expired/recharge required/please recharge", or content with similar meaning.
How to Build Queries
All four parameters arerequired：marketplace、keyword、startDate、endDate。
Principles for Building API Calls
- Site mapping: When the user says "US site" →
us, "Japan site" →jp, "Germany site" →de; when unspecified, default tous - Date format: Must be
YYYY-MM-DD, e.g.2025-01-05 - Time span：
startDatetoendDatemaximum 366 days; if exceeded, it needs to be split into multiple requests - Keywords: Pass in the keywords provided by the user as-is (lowercase English is preferred)
- Common time calculations：
- "Past 3 months" → endDate is today, startDate is about 90 days ago
- "All of last year" →
2025-01-01to2025-12-31 - "Peak season" → Judge based on the category, e.g. Q4 is
10-01to12-31
Common Query Scenarios
1. Check the search trend of the keyword over the past six months
{
"marketplace": "us",
"keyword": "yoga mat",
"startDate": "2025-10-01",
"endDate": "2026-03-31"
}
2. Determine the seasonality of the keyword (check full-year data)
{
"marketplace": "us",
"keyword": "christmas decorations",
"startDate": "2025-01-01",
"endDate": "2025-12-31"
}
3. Compare peak season and off-season search volume
Make two separate calls:
- Off-season:
startDate=2025-02-01,endDate=2025-04-30 - Peak season:
startDate=2025-10-01,endDate=2025-12-31
4. Multi-site comparison
Query different marketplaces separately for the same keyword (e.g. us、de、jp), and compare the search volume scale of each site.
5. Verify whether market demand is growing
{
"marketplace": "de",
"keyword": "luftreiniger",
"startDate": "2025-04-01",
"endDate": "2026-03-31"
}
Display Rules
- Trend visualization preferred: It is recommended to display search volume changes as a timeline/line chart, with the horizontal axis as the date period and the vertical axis as search volume
- Table assistance: Also provide a data table for precise reference, with columns including: period start date, period end date, search volume
- Trend summary: After the data, briefly summarize the trend direction (rising/falling/stable/cyclical fluctuation), and mark the peak and trough periods
- Peak annotation: Highlight the periods with the highest and lowest search volume, so users can quickly determine peak and off-season
- Error handling: When a query fails, explain the reason based on the error response and suggest adjusting parameters (e.g. date range exceeds 366 days)
Important Limitations
- Time span upper limit: A single query
startDatetoendDateis a maximum of 366 days; if exceeded, the query needs to be split - Data granularity: Weekly dimension (one data point every 7 days), not daily dimension
- Search volume type: Exact match search volume (Exact Match), not broad match
- All parameters are required：
marketplace、keyword、startDate、endDateNone can be omitted
User Expression & Scenario Quick Reference
Applicable - Historical trend analysis of keyword search volume:
| User Says | Scenario |
|---|---|
| "How has the search volume of this word changed" | Search volume trend query |
| "Does this category have seasonality" | Determine seasonal patterns from full-year data |
| "Is search volume rising or falling recently" | Recent trend determination |
| "When is the peak season" | Peak period identification |
| "What was the search volume in Q4 last year" | Search volume query for a specified time period |
| "Is this word popular on the Germany site" | Search volume query for non-US sites |
| "Compare the search volume of two time periods" | Peak/off-season or year-over-year comparison |
Not applicable - Beyond the keyword's historical search volume range:
- Keyword suggestions/keyword expansion (requires a keyword mining tool)
- Real-time/current search volume ranking (requires ABA or SIF tools)
- Keyword competition level, CPC bid
- Product sales, listing analysis
- Search volume on non-Amazon platforms
Boundary judgment: When users say "search volume," "keyword popularity," or "market demand trend," if they specifically want to see how a keyword's search volume changes over a period of time (historical trend), this skill applies. If they want the current ranking or a list of trending keywords, it does not apply.
Computing power consumption rules
Consumes 64 computing power.
Users pay for computing power consumption. Please fully assess: when this skill needs to be called frequently, or when users have insufficient expectations about the amount of computing power consumed, be sure to remind users and let users decide whether to continue.
Feedback:
Auto-detect and report feedback via the Feedback API when any of the following apply:
- The functionality or purpose described in this skill does not match actual behavior
- The skill's results do not match the user's intent
- The user expresses dissatisfaction or praise about this skill
- Anything you believe could be improved
Call the feedback API as specified in references/api.md. Do not interrupt the user's flow.
For more high-quality, professional cross-border e-commerce skills, visit LinkFox Skills.