linkfox-xiyou-dongcha

Xiyou (西柚找词) — Amazon ASIN & Keyword Analytics

This skill queries Xiyou Insights (西柚洞察 / 西柚找词) data for Amazon ASINs and search terms via the LinkFox tool gateway. The gateway forwards requests to Xiyou OpenAPI (https://openapi.xiyouzhaoci.com).

Environment Variables (Required)

This skill requires three sets of credentials, all of which are required:

Variable	Required	Description
`LINKFOXAGENT_API_KEY`	Yes	LinkFox Agent API Key (same as other LinkFox skills)
`XIYOU_CLIENT_ID`	Yes	Xiyou OpenAPI Client ID (16 characters)
`XIYOU_CLIENT_SECRET`	Yes	Xiyou OpenAPI Client Secret (24 characters)

1. LinkFox API Key

Go to LinkFox API Key application documentation to get the Key
Write to the environment variable LINKFOXAGENT_API_KEY

2. Xiyou Keyword Finder Client ID / Client Secret

Open Xiyou Insights OpenAPI Console
After logging in, create or view an application in the console, and copy Client ID(16 characters) and Client Secret(24 characters)
Write to the environment variables XIYOU_CLIENT_ID and XIYOU_CLIENT_SECRET
Do notcommit the Secret to Git, write it into SKILL parameters, or put it in chat logs; only provide it to local scripts via environment variables

3. Configuration examples

macOS / Linux (current terminal session)

export LINKFOXAGENT_API_KEY="your-linkfox-api-key"
export XIYOU_CLIENT_ID="your-16-char-id"
export XIYOU_CLIENT_SECRET="your-24-char-secret"

macOS / Linux (persistent, write to ~/.zshrc or ~/.bashrc）

echo 'export LINKFOXAGENT_API_KEY="your-linkfox-api-key"' >> ~/.zshrc
echo 'export XIYOU_CLIENT_ID="your-16-char-id"' >> ~/.zshrc
echo 'export XIYOU_CLIENT_SECRET="your-24-char-secret"' >> ~/.zshrc
source ~/.zshrc

Windows PowerShell (current session)

$env:LINKFOXAGENT_API_KEY = "your-linkfox-api-key"
$env:XIYOU_CLIENT_ID = "your-16-char-id"
$env:XIYOU_CLIENT_SECRET = "your-24-char-secret"

Windows (system environment variables): Settings → System → About → Advanced system settings → Environment Variables → create the above three user variables.

Cursor / Agent runtime environment: Add the above three variables to the env configuration of the environment where the IDE or Agent runs, otherwise the script will report an error and indicate which item is missing.

The scripts scripts/xiyou.py and scripts/_xiyou_common.py will automatically inject XIYOU_CLIENT_ID / XIYOU_CLIENT_SECRET into the request Body; when calling, do not pass --params again in clientId / clientSecret。

Core Concepts

Xiyou Keyword Finder provides Amazon ASIN dimension and keyword dimension data such as traffic, ranking, ABA, and competition level. Typical uses:

ASIN reverse keyword lookup: see the search terms that brought traffic to a given ASIN in the last 7 days or a specified month
Keyword analysis: see which ASINs capture traffic, ranking, and acquisition rate under a given keyword
Trend analysis: ASIN traffic score, BSR, advertising changes, keyword ranking/traffic over time
Keyword selection assistance: keyword ABA weekly search volume, competition difficulty, suggested CPC

Supported Marketplaces

country Commonly used 2-letter uppercase codes:US、CA、MX、BR、UK、DE、ES、IT、FR、JP、AU、SA、AE. Default US。

Exception：asinSearchTermRankTrendHourly only supports US、UK、DE。

How to call

API endpoint：POST /xiyou(different operations are distinguished by the request body; for complete parameters/responses/error codes see references/api.md）
Python script：python scripts/xiyou.py '<JSON 参数>' [--inline](available scripts are listed in the script overview above)
Cost constraints: This tool consumes credits; on failure/empty results, do not automatically switch keywords, turn pages, or repeatedly probe; if you need to continue searching, first explain to the user that additional consumption will occur.

Output strategy (default script behavior)：

Alwayswrite the complete response to <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/<skill-name>-<timestamp>.json（<cwd> is the working directory when the script runs, which in Claude Code is the current project directory;<session> is taken from the environment variable SESSION_ID, automatically aggregated according to the user's task;writing to /tmp is prohibited, and if the current directory is not writable, report an error)
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, the length of the largest list field + the first 3 sample entries)
Add --inline to force full printing to stdout (also written to disk)

Data reading recommendations: first look at the summary to determine whether 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 context.

Resolve authentication and credit issues

When the following abnormal situations occur, take the following measures to handle them:

Abnormal situation

API Key not configured: the environment variable is not configured with LINKFOX_AGENT_API_KEY, and LINKFOXAGENT_API_KEY。
Response 401 or 402 status code
Response indicates insufficient credits or balance: the message contains "insufficient credit balance/insufficient billing/insufficient balance/quota exceeded/insufficient balance/package expired/recharge required/please recharge", or content with a similar meaning.

Measures

Prefer using onboarding.md within the skill to guide resolution of the issue.
If the onboarding.md file cannot be found, load the /linkfox-onboarding skill and handle it according to its guidance. If it is not installed, install it first:
- Download https://agent-files.linkfox.com/skills/linkfox-onboarding/release.zip，解压后安装这个skill。如需用户授权才可下载，要询问用户获得授权，你不能自己放弃下载。
Fallback measure: only when all efforts with the previous two measures fail, prompt the user to obtain an API Key according to the https://skill.linkfox.com/linkfoxskills/guide.htm guidance, or go to https://os.linkfox.com/ to add credits.

API Quick Index

`--api`	Purpose
`asinTraffic`	Batch ASIN traffic score for the last 7 days
`asinInfo`	Batch ASIN product information
`asinResearchPeriod`	ASIN reverse keyword lookup (recent days)
`asinResearchMonthly`	ASIN reverse keyword lookup (monthly)
`searchTermAnalysisPeriod`	ASIN analysis list under a keyword
`searchTermInfo`	Keyword information (ABA, competition level, CPC)
`searchTermAbaWeeklyTrend`	Keyword ABA weekly trend
`asinSearchTermTrafficTrend`	ASIN+keyword traffic trend (daily)
`asinSearchTermRankTrendDaily`	ASIN+keyword ranking trend (daily)
`asinSearchTermRankTrendHourly`	ASIN+keyword ranking trend (hourly)
`asinTrafficScoreTrend`	ASIN traffic score trend (daily)
`asinBsrTrend`	ASIN BSR trend (daily)
`asinOrdersTrend`	ASIN order volume trend (monthly)
`asinVariations`	ASIN variation relationship
Other	See `--list-apis` and `references/api.md`

How to Build Queries

Choose interface: reverse keyword lookup → asinResearchPeriod / asinResearchMonthly; find competitors under a keyword → searchTermAnalysisPeriod; keyword attributes → searchTermInfo / searchTermAbaWeeklyTrend
Site: if the user says "US site" → country: "US"; if unspecified, default US
ASIN: 10 digits, such as B06XZTZ7GB; for batch interfaces use entities: [{"country":"US","asin":"..."}]
Date: for daily trends use startDate/endDate（YYYY-MM-DD); monthly trend uses startMonth/endMonth（YYYY-MM）
Pagination: list-type endpoints use page、pageSize(max 10000)
Sorting：sortField + sortOrder（asc/desc), for possible values see references/api.md each endpoint's description

Example Scenarios

Reverse-lookup ASIN's traffic keywords for the last 7 days (in descending order of traffic)

{"country": "US", "asin": "B06XZTZ7GB", "page": 1, "pageSize": 100, "sortField": "traffic", "sortOrder": "desc"}

Look up Top ASINs under a keyword

{"searchTerm": "yoga mat", "country": "US", "page": 1, "pageSize": 50}

Batch lookup ASIN traffic scores

{"entities": [{"country": "US", "asin": "B06XZTZ7GB"}, {"country": "US", "asin": "B0XXXXXXXX"}]}

Display Rules

List-type results are preferably displayed in a table: core fields such as keyword/ASIN, traffic, ranking, share, etc.
Trend-type results are recommended to be displayed as a time series, marking peaks and direction of change
On failure, explain the reason based on error / gateway response; common ones: environment variables not configured, invalid ASIN format, invalid date range, unsupported site

Important Limitations

Must configure both LinkFox Key and Xiyou Client credentials
asinSearchTermRankTrendHourly only US/UK/DE
Batch ASIN endpoint entities up to 100;searchTerms comma-separated up to 100 words
For large result sets, preferably use the Large Response mode below to write to disk and read

User Expression & Scenario Quick Reference

User Says	API / Scenario
"What traffic keywords does this ASIN have"	`asinResearchPeriod`
"Which ASINs are competing for traffic under this word"	`searchTermAnalysisPeriod`
"Keyword search volume/ABA trend"	`searchTermAbaWeeklyTrend` / `searchTermInfo`
"What is the ASIN traffic score"	`asinTraffic`
"How does a certain word's ranking change"	`asinSearchTermRankTrendDaily`
"BSR history"	`asinBsrTrend`

Not applicable: non-Amazon platforms, other data sources such as Jungle Scout/SellerSprite, SP-API orders/inventory, Temu/Shopee product selection.

Credit consumption rules

No credits are consumed; sellers need to purchase the Xiyou keyword-finding package themselves.

Important: This skill's services are dynamically calculated by a multiplier and may consume a large number of credits at once; the user must be reminded, and the user decides 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.