linkfox-geekbi-temu-product

Temu Product Search & Detail

This skill supports a dependency-aware Temu product research workflow:

1. Resolve a marketplace with the site-list endpoint when regionId is unknown.
2. Resolve category IDs with the category-list endpoint when category filtering is needed.
3. Search products with the selected regionId and optional catIds.
4. Fetch one product's detail and recent 30-day history with goodsId and the same regionId.

Use only the endpoints needed for the user's request. Read references/api.md for the complete request and response contract.

The site-list and category-list endpoints are helper capabilities for product search/detail. A request solely for site or category metadata must not auto-select this skill. If the user explicitly invokes this skill, or the skill is already active, siteList or categoryList may be called independently.

Core Concepts

• regionId is the marketplace selector. Get a non-null positive value from sites[].regionId; never substitute siteId.
• catIds is an array of category IDs for product search. Populate it only from non-null categories[].catId values.
• parentCatId drills into the category tree. Omit it for top-level categories, then reuse a returned catId to fetch children.
• Search returns paginated items[]; detail requires one goodsId and returns goods plus history[].
• The default marketplace is regionId: 211 (United States). Search defaults are page: 1, size: 20, and matchMode: 2.
• Treat every paid endpoint call as a new charge. Within one session, call the same endpoint and parameters only once unless the user explicitly asks to repeat it.

Intent	Endpoint	Script
Search and filter products	/geekbi/temu/goodsSearch	geekbi_temu_goods_search.py
Inspect one product and history	/geekbi/temu/goodsDetail	geekbi_temu_goods_detail.py
Resolve Temu marketplaces	/geekbi/temu/siteList	geekbi_temu_site_list.py
Browse the category tree	/geekbi/temu/categoryList	geekbi_temu_category_list.py

Shared Product Response Fields

Path	Meaning
items[] / goods	Product identity, category, sales, revenue, price, rating, inventory, status, and timing fields

Endpoints

/geekbi/temu/goodsSearch

Request

• regionId, page, and size select the marketplace and page; page * size must not exceed 10,000.
• keyword matches the title. matchMode is 1 for strict or 2 for fuzzy matching.
• catIds accepts an integer array, for example [984, 982].
• Range filters use paired *Min / *Max fields for sales units, revenue, price, supply price, rating, reviews, inventory, and growth rates. Never make a minimum greater than its maximum.
• status is an integer array whose elements may be 1 (normal), 2 (out of stock), or 3 (delisted). hostingMode is 1 (full-managed) or 2 (semi-managed).
• onSaleTimeMin/Max and mallOpenTimeMin/Max use ISO-8601 date-time strings.
• order is asc or desc; use only a sort field accepted by the API or returned in an established workflow.

Response

Path	Meaning
items[].goodsId	Product ID accepted by the detail endpoint

/geekbi/temu/goodsDetail

Request

• goodsId is required and normally comes from search items[].goodsId.
• Pass the same regionId used for search so prices and market context remain consistent. Only reuse a non-empty items[].goodsId; stop and explain when search returns no valid ID.

Response

Path	Meaning
history[]	Up to 30 days of daily sales, revenue, price, inventory, rating, reviews, and growth metrics

/geekbi/temu/siteList

Request

• Site list takes {}. Use only a non-null positive regionId from its response, never siteId.

Response

Path	Meaning
sites[].regionId	Marketplace ID accepted by search and detail
sites[].siteId	Upstream internal ID; do not use for business filtering

/geekbi/temu/categoryList

Request

• Category list takes {} for top-level categories or {"parentCatId": <catId>} for children; reuse only a non-null valid catId.

Response

Path	Meaning
categories[].catId	Category ID accepted in search catIds and category parentCatId

Common Response Rules

Path	Meaning
errcode / errmsg	Gateway business status; the verified success shape is 200 / ok

Business fields may be absent or null. Preserve the runtime JSON type and do not replace missing values with zero.

Helper Endpoint Rule

• For a helper-only request, call only the requested free helper endpoint. Do not invoke goodsSearch or goodsDetail unless the user also requests product data.

How to call

• API endpoint：POST /geekbi/temu/goodsSearch、POST /geekbi/temu/goodsDetail、POST /geekbi/temu/siteList or POST /geekbi/temu/categoryList(for full parameters/response/error codes see references/api.md）
• Python script：python scripts/geekbi_temu_goods_search.py '<JSON 参数>' [--inline]、python scripts/geekbi_temu_goods_detail.py '<JSON 参数>' [--inline]、python scripts/geekbi_temu_site_list.py '{}' [--inline] or python scripts/geekbi_temu_category_list.py '<JSON 参数>' [--inline]
• Cost constraints: product search/product details each consume 15 compute units per call, site/category lists do not consume compute units; the same endpoint with the same parameter combination uses a 24h local cache, and the same session by default calls only once.--inline does not bypass the cache;--no-cache skips cache reads and writes and forces a real request, paid endpoints may deduct compute units again, and free auxiliary endpoints only force a refresh. Failures, empty results, or transient errors must not be automatically retried, nor must keywords, pages, or sites be automatically changed for continuous probing; when paid retrieval needs to continue, first explain to the user that additional consumption will occur.

Output strategy (script default behavior)：

• Alwayswrite the complete response to <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-geekbi-temu-product-<timestamp>.json；<cwd> is the current working directory when the script runs,<session> is taken from the environment variable SESSION_ID, and is automatically generated when not set. If the current directory is not writable, report an error directly and do not fall back to the user directory or system temporary directory.
• 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,errcode/errmsg/total and other common fields, the length of the largest business list + the first 3 samples; ignore columns rendering metadata)
• 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 putting the entire JSON into the context.

Resolve authentication and compute unit issues

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

Abnormal situation

• API Key not configured: the environment variable is not configured LINKFOX_AGENT_API_KEY or the compatible key LINKFOXAGENT_API_KEY。
• Response 401 or 402 status code。
• Response indicates insufficient compute units or balance: the message contains "insufficient compute unit balance/insufficient billing/insufficient balance/quota exceeded/insufficient balance/package expired/recharge required/please recharge" or similar meaning.

Usage Examples

# Search products; catIds contains categories[].catId values
python scripts/geekbi_temu_goods_search.py '{"regionId":211,"keyword":"dress","catIds":[984],"page":1,"size":20,"sort":"sold","order":"desc"}'

# Reuse items[].goodsId and the same regionId
python scripts/geekbi_temu_goods_detail.py '{"goodsId":"<goodsId from search>","regionId":211}'

# Resolve regionId (use sites[].regionId, not siteId)
python scripts/geekbi_temu_site_list.py '{}'

# Browse top-level categories, then fetch one node's children
python scripts/geekbi_temu_category_list.py '{}'
python scripts/geekbi_temu_category_list.py '{"parentCatId":100}'

Display Rules

1. State the selected marketplace (regionId, site name, and currency when available), filters, page, and page size.
2. For search results, show product title, goodsId, price range, total/monthly sales, revenue, rating, reviews, inventory, shop, category, status, and listing time when returned.
3. For detail, group the current product profile separately from the 30-day history. Label the date/time field used for each historical row.
4. Treat rate fields as percentages only when the response contract identifies them as rates; do not silently convert units.
5. Keep category IDs and product IDs available for follow-up calls, but do not expose internal siteId as a marketplace selector.
6. Preserve null and unavailable fields rather than inventing values.

Important Limitations

• This skill intentionally packages four related endpoints as one product workflow. Keep each script's API_PATH and business-list summary behavior independent.
• This skill researches public Temu market data; it does not access or operate a seller account.
• Search is limited to the first 10,000 matching records, with size from 1 to 200.
• Detail requires an exact goodsId; it cannot infer one from a title alone.
• Monetary values follow the selected site's currency, except supply-price filters explicitly documented in CNY.
• Product fields and history fields may be missing or null; upstream extensions can appear under extraFields.
• Do not automatically call site/category helpers when the user already supplied valid IDs.
• Do not retry a paid endpoint with changed filters after an empty result without user confirmation.

User Expression & Scenario Quick Reference

Applicable: "Use GeekBI to query Temu products", "Look at the details of this goodsId and the last 30 days trend", "Check Temu product supply price and inventory", "Compare daily/weekly/monthly sales or sales revenue growth", "linkfox-geekbi-temu-product".

Adjacent: Within an active product search/detail workflow, use the free helper endpoints when a requested site or category has no known ID. When the user explicitly invokes this skill, or this skill is already active, either helper may also be called independently without calling a paid product endpoint. Category-name resolution may require starting at the top level and following parentCatId through multiple levels. When the user supplies a product URL but no goodsId, extract only if the ID is unambiguous; otherwise ask for it.

Not an automatic trigger: A request solely to enumerate Temu sites, regionId values, categories, or catId values, unless the user explicitly invokes this skill or the skill is already active.

Not applicable: Generic Temu keyword/category/price/rating/sales filtering without GeekBI-specific fields (use linkfox-temu-product-query); Temu seller-center orders, inventory updates, listing publication, fulfillment, account authorization, advertising operations, or research on another marketplace. Unless the user explicitly requests cross-source comparison, do not call both paid product-data skills.

Compute unit consumption rules

Product search and product details each consume 15 compute units per call; site lists and category lists do not consume compute units.

Users will pay compute units for product search and product details. Before high-frequency calls, paging, or continuing from search to query multiple product details, the user must decide whether to continue.

Feedback:

Auto-detect and report feedback via the Feedback API when any of the following apply:

1. The functionality or purpose described in this skill does not match actual behavior
2. The skill's results do not match the user's intent
3. The user expresses dissatisfaction or praise about this skill
4. 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.