linkfox-sorftime-walmart-category-market

Walmart Category Market Research

Use Sorftime data to retrieve the Walmart US category hierarchy, match a natural-language category name, or inspect one category's market report and returned Best Seller products.

Core Concepts

• Send exactly one operation per request. Do not automatically chain operations; each call consumes Sorftime Requests.
• tree returns the complete category hierarchy and needs no other business parameter.
• searchByName accepts a natural-language category name and returns up to three related category matches.
• marketReport requires a known nodePath. Never guess the path from a category name.
• All fields are flat at the top level of the JSON body. operation values are case-sensitive.

Operation Routing

Intent	operation	Other parameters	Sorftime Request
Download the category tree	tree	None	5
Match a natural-language category name	searchByName	name	1
Query a category market report	marketReport	nodePath	5

Complete parameter and response details are in references/api.md.

How to Call

• API Endpoint：POST /sorftime/walmart/categoryMarket(for full parameters/responses/error codes, see references/api.md）
• Python Script：python scripts/sorftime_walmart_category_market.py '<JSON 参数>' [--inline]
• Cost Constraints: This tool consumes compute; by default, the same parameter combination is called only once per session, and the script has a 24h local cache. On failure/empty results, do not automatically try different keywords, paginate, or change the zip code to probe continuously; if further retrieval is needed, first explain to the user that it will incur additional consumption.

Output Strategy (Script Default Behavior)：

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

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

Resolve 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

Usage Examples

python scripts/sorftime_walmart_category_market.py '{"operation":"tree"}'
python scripts/sorftime_walmart_category_market.py '{"operation":"searchByName","name":"patio furniture"}'
python scripts/sorftime_walmart_category_market.py '{"operation":"marketReport","nodePath":"4044_623679_1032619_5842891_9823303"}'

Prefer searchByName when the user supplies a natural-language category name. Use tree only when full hierarchy traversal is required. A tree response can be approximately 10 MB; normally inspect its saved JSON selectively rather than using --inline.

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. For tree, show matched category names, their ID hierarchy, and the derived nodePath; never dump the full tree into conversation.
3. For searchByName, show at most the returned three NodeId and CategoryName pairs; label them as related matches rather than exact classification.
4. For marketReport, summarize only returned metrics and present Best Seller products compactly.
5. State the number of Best Seller products actually returned and do not present the result as the entire category catalog.
6. Preserve upstream field meanings and never invent missing category relationships or metrics.

Important Limitations

• All three operations target Walmart US (domain=21 is applied by the backend).
• Sorftime may omit categories unsuitable for third-party sellers; absence does not prove Walmart has no such category.
• marketReport accepts a numeric underscore-delimited nodePath, not a free-text category name.
• searchByName returns no more than three related categories and does not guarantee an exact match.
• tree and marketReport consume 5 upstream requests each; searchByName consumes 1. Do not retry or run another operation without user authorization.
• This skill does not cover product or keyword data.

User Expression & Scenario Quick Reference

Applicable: Walmart category tree, natural-language category matching, category NodeId/path, category market, and category Best Seller requests.

Not applicable: product detail/trend/sales, keyword metrics, or saved-keyword management.

Boundary judgment: If the primary object is a Walmart product ID, use product analysis. Use searchByName for a category name, tree for hierarchy traversal, and marketReport for a known category path.

Compute Consumption Rules

Billing follows dynamic rules: a single Sorftime Request is currently shown as 6 compute; multi-Request operations are calculated by the gateway as a whole order and rounded, and the final amount is subject to 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. You must remind the user and let the user decide whether to continue executing another operation.

Feedback:

Auto-detect and report feedback via the Feedback API when the skill behavior or result mismatches intent, the user expresses praise or dissatisfaction, or an improvement is apparent. Call it as specified in references/api.md without interrupting the user's flow.

---

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