Temu Category & Keyword Demand Research

This skill researches Temu category opportunities and buyer-demand keywords from public marketplace data. Use only the endpoints needed for the user's request, and read references/api.md for the full request and response contract.

The site-list and category-list endpoints are helper capabilities. A helper-only request must not auto-select this skill unless the user explicitly invokes it or the skill is already active.

Core Concepts

• regionId selects the marketplace. Resolve it from a non-null positive sites[].regionId; never substitute siteId. The gateway default is regionId: 211 (United States).
• dsr is a supply-demand signal, not a standalone go/no-go score. Cross-check demand scale, recent growth, item/shop supply, and price.
• Search responses are paginated items[]. Defaults are page: 1 and size: 20; size is 1–200 and page * size must not exceed 10,000. order has no gateway default; when supplied, it must be asc or desc (case-insensitive).
• Range filters are limited to dsr, totalSold, avgPrice, totalSales, itemCount, and mallCount, each with Min / Max. Never make a minimum greater than its maximum; all except dsr must be non-negative.
• Use site/category helpers only when the user has not supplied a valid ID. Stop if no unambiguous ID is returned.
• Do not launch a paid search merely to answer a site-list or category-tree request.

Endpoint: /geekbi/temu/categorySearch

Request

• Category research uses keyword to compare market capacity and competition. Use the separate category-list helper with parentCatId when a trusted category tree must be traversed; categorySearch itself does not accept catLevel or parentCatId.
• Use keyword for a Chinese or English category name. catLevel and parentCatId are response/helper concepts, not categorySearch request fields.
• Filter or rank broad demand with totalSold; use dsr for candidate discovery. Treat monthSoldRate and monthSalesRate as response fields for recent-growth analysis, not as range-filter request fields.
• itemCount and mallCount can be filtered with Min/Max fields. Period *ItemCount and *MallCount values are response-only changes and can be negative.

# Compare US pet-related categories by cumulative demand
python scripts/geekbi_temu_category_search.py '{"regionId":211,"keyword":"宠物","totalSoldMin":1000,"sort":"totalSold","order":"desc","page":1,"size":20}'

Response

Endpoint: /geekbi/temu/keywordSearch

Request

• Keyword research uses keyword for a specific phrase or catIds for category-led discovery. Combine them only when the user explicitly wants a phrase within a category.
• Resolve catIds from valid categories[].catId values or a verified category-search result. Prefer level-1 or level-2 IDs for broad discovery.
• Search a supplied phrase with keyword without silently translating or replacing it.
• For category-led discovery, use catIds from the category helper. Multiple IDs match any supplied category.
• Rank hot terms with totalSold and blue-ocean candidates with dsr. Analyze recent demand from returned monthSoldRate or monthSalesRate; these period metrics are not range-filter request fields. Use firstOnSaleTimeMin/Max for market recency.
• firstOnSaleTimeMin/Max use ISO-8601 timestamps and describe the earliest associated product listing time.

# Discover dress-related demand terms within a verified category
python scripts/geekbi_temu_keyword_search.py '{"regionId":211,"keyword":"dress","catIds":[27011],"totalSoldMin":1000,"sort":"totalSold","order":"desc","page":1,"size":20}'

Response

Endpoint: /geekbi/temu/siteList

Request

# Resolve a non-US marketplace; use regionId, not siteId
python scripts/geekbi_temu_site_list.py '{}'

Response

Endpoint: /geekbi/temu/categoryList

Request

# Resolve a trusted category path when only a category name is known
python scripts/geekbi_temu_category_list.py '{}'
python scripts/geekbi_temu_category_list.py '{"parentCatId":27011}'

Response

Fields can be absent or null. Preserve runtime JSON types and raw rate values; do not replace missing values with zero.

调用方式

• API 端点：POST /geekbi/temu/categorySearch、POST /geekbi/temu/keywordSearch、POST /geekbi/temu/siteList 或 POST /geekbi/temu/categoryList（完整参数/响应/错误码见 references/api.md）
• Python 脚本：python scripts/geekbi_temu_category_search.py '<JSON 参数>' [--inline]、python scripts/geekbi_temu_keyword_search.py '<JSON 参数>' [--inline]、python scripts/geekbi_temu_site_list.py '{}' [--inline] 或 python scripts/geekbi_temu_category_list.py '<JSON 参数>' [--inline]
• 成本约束：类目搜索和关键词搜索各消耗 15 算力/次，站点列表和品类列表不消耗算力；同一端点同一参数组合使用 24h 本地缓存，同一会话默认只调用一次。--inline 不绕过缓存；--no-cache 会跳过缓存读写并强制真实请求，付费端点可能再次扣算力，免费辅助端点仅强制刷新。失败、空结果或瞬时错误不得自动重试，也不得自动换关键词、翻页、改站点或筛选条件连续试探；需要继续付费检索时先向用户说明会产生额外消耗。

输出策略（脚本默认行为）：

• 始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-geekbi-temu-market-research-<timestamp>.json；<cwd> 为脚本执行时的当前工作目录，<session> 取自环境变量 SESSION_ID，未设置时自动生成。当前目录不可写时直接报错，不回退到用户目录或系统临时目录。
• 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout
• 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层状态字段、常见业务计数、忽略 columns 后最大业务列表的长度 + 前 3 条样本）
• 加 --inline 强制全量打印到 stdout（同样落盘）

读数据建议：先看摘要判断是否足够；需要具体字段时优先用 jq或ConvertFrom-Json 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。

解决认证和算力问题

发生以下异常情况时，采用 references/onboarding.md 引导解决问题：

异常情况

• 未配置 API Key：环境变量未配置 LINKFOX_AGENT_API_KEY 或兼容键 LINKFOXAGENT_API_KEY。
• 响应 401 或 402 状态码。
• 响应提示算力或余额不足：消息含“算力余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值”或类似含义。

Display Rules

1. State marketplace name, regionId, currency, filters, sort, page, and page size.
2. For categories, show the full category path, catId, level, demand/revenue, average price, item/shop supply, semi-managed supply, and relevant growth fields.
3. For keywords, show the phrase, associated category path/IDs, demand/revenue, average price, item/shop supply, semi-managed supply, earliest listing time, and relevant growth fields.
4. Label monetary values with the selected site's currency. Keep raw rate units explicit and do not silently convert them.
5. Mark incomplete pagination as a sample. Keep IDs available for downstream product, shop, or keyword research.
6. Preserve null, missing fields, and upstream extensions rather than inventing values.

Important Limitations

• This skill researches public Temu market data; it does not access or operate a seller account.
• total can be capped at 10,000. A partial page or uncompleted pagination is not the entire marketplace.
• dsr, growth, sales, or supply alone cannot prove an opportunity or predict future performance.
• firstOnSaleTime is the earliest associated product listing time, not keyword creation time.
• The category tree can require several parentCatId calls; do not guess intermediate IDs.
• Do not automatically call helpers when valid IDs are already available.
• Do not retry paid endpoints with changed filters or another page after empty results without user confirmation.

User Expression & Scenario Quick Reference

Applicable: “查 Temu 美国站宠物类目机会”, “找月需求增长的蓝海类目”, “挖 Temu 连衣裙热搜词”, “比较关键词供需和价格带”, “Temu category/keyword demand research”.

Adjacent: Resolve an unknown non-US marketplace before research. For category-led keyword discovery, resolve a trusted catId from the category tree or a verified category result.

Not an automatic trigger: A request solely to enumerate Temu sites, regionId values, category-tree nodes, or catId values does not auto-trigger this skill. Route category-tree/catId-only requests to linkfox-temu-category-search. If this GeekBI skill was explicitly invoked or is already active, its site/category helpers may be called independently.

Not applicable: Temu product detail, shop-only benchmarking, review analysis, seller-center operations, listing changes, fulfillment, advertising, or research on another marketplace.

算力消耗规则

类目搜索和关键词搜索每次各消耗 15 算力；站点列表和品类列表不消耗算力。

用户会为类目搜索和关键词搜索支付算力。高频调用、翻页或改条件重搜前，必须让用户决定是否继续。

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.