linkfox-sorftime-walmart-keyword-research

Walmart Keyword Research

Use one Sorftime endpoint to research Walmart US keywords or explicitly manage the saved-keyword library.

Core Concepts

• Send exactly one operation per request. Never run multiple keyword operations as an automatic discovery chain.
• Use a flat JSON body. The only business nesting is the optional pattern object for marketQuery.
• operation values are case-sensitive. A different operation, page, or filter is another paid call.
• favoriteAdd and favoriteChange mutate external account data and require an explicit, unambiguous user request.

Operation Routing

Intent	operation	Required input	Sorftime Request
Filter current hot keywords	marketQuery	None; filters optional	5
Find hot keywords from a name	searchByName	name	1
Find products for a hot keyword	searchProducts	keyword	5
Inspect keyword metrics	detail	keyword	1
Find a product's associated keywords	productKeywords	productId	1
Expand related keywords	relatedKeywords	keyword	5
Add a saved keyword	favoriteAdd	keyword	1
Delete or move a saved keyword	favoriteChange	keyword, command	0
List saved keywords or folders	favoriteList	command	1

Read references/api.md for the complete conditional parameter matrix before calling.

Parameter Guide

• marketQuery: optional pattern.keyword, pattern.rankCondition, and pattern.searchVolumeCondition; pageIndex defaults to 1 and pageSize to 20 (20–200).
• A one-value condition such as [10000] is a lower bound. [0,10000] follows Sorftime's documented less-than-10000 semantics.
• searchByName: name is a product or category name; pageIndex defaults to 1, and Sorftime returns at most 200 rows per page.
• searchProducts, productKeywords, and relatedKeywords: pagination defaults to page 1 and 20 rows, maximum 200.
• favoriteList exposes pageIndex (default 1); the backend maps it to Sorftime's upstream Page field.

How to Call

• API Endpoint：POST /sorftime/walmart/keywordResearch(for full parameters/responses/error codes see references/api.md）
• Python Script：python scripts/sorftime_walmart_keyword_research.py '<JSON 参数>' [--inline]
• Cost Constraints: This tool consumes compute; read-only research operations use a 24h local cache for the same parameter combination,favoriteAdd、favoriteChange、favoriteList always bypasses the cache. On failure/empty results, do not automatically switch keywords, page through, or change the zip code to probe repeatedly; if you need to continue searching, first explain to the user that it will incur additional consumption.

Output Strategy (Script Default Behavior)：

• Alwayswrite the full response to <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-sorftime-walmart-keyword-research-<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 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 full 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 --inline to force full printing to stdout (also written to disk)

Data Reading Suggestions: First look at the summary to judge whether it is sufficient; when specific fields are needed, prefer jqorConvertFrom-Json to extract on demand from the saved json file, avoiding bringing the entire JSON into context.

Resolving Authentication and Compute Issues

When the following abnormal situations occur, use references/onboarding.md to guide problem resolution:

• API Key not configured: The environment variable is not configured LINKFOX_AGENT_API_KEY, and LINKFOXAGENT_API_KEY
• Response 401 or 402 status code
• Response indicates insufficient compute or balance: The message contains “insufficient compute balance/insufficient billing/insufficient balance/quota exceeded/insufficient balance/package expired/recharge required/please recharge” or similar meaning

Keyword Library Safety

• Add to the default “未分类” folder by omitting dict; a provided folder may be created by Sorftime.
• Delete with command="del". Omitting dict operates on the default “未分类” folder; specify dict to delete from another folder.
• Move with command="move=<目标目录>". Omitting dict means the source is “未分类”.
• List with command equal to all, dict, or dict=<目录>.
• If an explicitly authorized mutation truly must be repeated after external state changed, use --no-cache; never use it to bypass the confirmation guard.
• favoriteAdd, favoriteChange, and favoriteList always bypass the local cache, so mutations are never suppressed and list results reflect the latest upstream state.
• The exposed operations do not delete folders. Removing the final keyword can leave an empty folder in the API library.

Usage Examples

python scripts/sorftime_walmart_keyword_research.py '{"operation":"marketQuery","pattern":{"keyword":"wireless","searchVolumeCondition":[10000]},"pageIndex":1,"pageSize":20}'
python scripts/sorftime_walmart_keyword_research.py '{"operation":"detail","keyword":"wireless earbuds"}'
python scripts/sorftime_walmart_keyword_research.py '{"operation":"productKeywords","productId":"5169493923","pageIndex":1,"pageSize":20}'
python scripts/sorftime_walmart_keyword_research.py '{"operation":"favoriteList","command":"dict","pageIndex":1}'

Run mutation operations only after explicit authorization.

Display Rules

1. State the selected operation and show requestConsumed, costCredit, and costToken when returned. If _cache.hit=true, make clear that the cached values describe the original live request and no new production charge occurred.
2. Preserve metric meanings and observation windows; do not turn estimates into guaranteed demand or sales.
3. Report the requested page and offer another only after explaining that it creates another paid call.
4. Treat product IDs and keywords as strings.
5. For mutations, report the returned data code; HTTP 200 alone does not prove mutation success.

Important Limitations

• This integration targets Walmart US only.
• Current-hot-keyword data, the 15-day product window, and the 30-day product-keyword window are Sorftime constraints.
• A single saved-keyword folder supports at most 2,000 keywords.
• The API saved-keyword library is separate from Sorftime Professional favorites; data is not synchronized between them.
• Read the Sorftime business response from data.value; its JSON shape varies by operation.
• Empty results must not trigger automatic variants, pagination, or related-keyword calls.
• This skill excludes Sorftime Walmart “其他” APIs.

User Expression & Scenario Quick Reference

Applicable: Walmart keyword discovery, keyword metrics, product-to-keyword research, related terms, or an explicit saved-keyword-library action.

Not applicable: category-market reports, product detail/trend analysis, or any Sorftime Walmart “其他” capability.

Boundary judgment: Choose exactly one operation that matches the user's stated intent; never turn one keyword request into an automatic multi-step research chain.

Compute Consumption Rules

Billed according to dynamic rules: a single Sorftime Request currently shows as 6 compute; multi-Request operations are calculated by the gateway as a whole order and rounded, with the final amount based on the costCredit returned by the entry script; do not simply use requestConsumed × 6 in place of the actual bill.

Users pay fees due to compute consumption. Before high-consumption filtering, expanded terms, or continuous paging, you must remind the user; any favorite changes must be explicitly authorized.

Feedback:

Auto-detect and report feedback via the Feedback API when behavior or results mismatch intent, the user expresses praise or dissatisfaction, or an improvement is apparent. Follow references/api.md without interrupting the user's flow.

---

For more high-quality, professional cross-border e-commerce skills, visit LinkFox Skills.