nexscope-ai/nexscope-ecommerce-skills / ecommerce-geekbi-temu-product
ecommerce.geekbi-temu-product
VerifiedSearch public Temu products and inspect product details and recent history through Nexscope.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.1 KB |
| manifest.json | config | 519 B |
| references/api.md | markdown | 20.2 KB |
| references/testing.md | markdown | 1.2 KB |
| scripts/geekbi_temu_category_list.py | script | 18.0 KB |
| scripts/geekbi_temu_goods_detail.py | script | 18.3 KB |
| scripts/geekbi_temu_goods_search.py | script | 26.3 KB |
| scripts/geekbi_temu_site_list.py | script | 17.9 KB |
references/api.md
View on GitHub# Nexscope migration contract
- All callable routes use `${NEXSCOPE_PROXY_BASE}/api/v1/tools/research/`.
- Authentication is `Authorization: Bearer <NEXSCOPE_API_KEY>`.
- Successful transport responses use the Nexscope envelope; the provider business response is nested in `data`.
- This operation consumes credits. Preserve `X-Cost-Token` and `X-Cost-Credit` from response headers as server-reported billing metadata; do not inherit or convert source-platform point values.
- HTTP 401 means Nexscope authentication failed. HTTP 402 means insufficient Nexscope credits. Do not retry paid or ambiguous failures automatically.
# Temu Product Search and Detail API Reference
## API Specification
- **Endpoint (Product Search)**: `${NEXSCOPE_PROXY_BASE}/api/v1/tools/research/geekbi/temu/goodsSearch`
- **Endpoint (Product Detail)**: `${NEXSCOPE_PROXY_BASE}/api/v1/tools/research/geekbi/temu/goodsDetail`
- **Endpoint (Site List)**: `${NEXSCOPE_PROXY_BASE}/api/v1/tools/research/geekbi/temu/siteList`
- **Endpoint (Category List)**: `${NEXSCOPE_PROXY_BASE}/api/v1/tools/research/geekbi/temu/categoryList`
- **HTTP Method**: POST, `Content-Type: application/json`
- **Authentication**: Header `Authorization: Bearer <api_key>`; api_key is read first from the `NEXSCOPE_API_KEY` environment variable
- **User-Agent**:`Nexscope-Skill/1.0`
- **Forwarded Headers**: `SESSION_ID`, `MESSAGE_ID`, `MODE_ID`, `APP_NAME` (empty strings when unset)
- **Timeout**: 150s
> By default, entry scripts cache only successful responses for 24 hours, including successful empty results; HTTP or business failures are not cached. `--inline` does not bypass the cache; `--no-cache` skips cache reads/writes and forces a live request. Product search/detail calls may consume compute credits again; site/category lists are only forcibly refreshed.
> These URLs are Nexscope tool gateway routes. The server then calls the Nexscope upstream GET API; clients must not use upstream `/api/v1/temu/...` paths as gateway URLs.
## Common Gateway Success Fields
Live integration verification summary: the site list returned 33 sites, including the United States with `regionId=211`; first-level categories returned 23 nodes, and children of `parentCatId=27011` returned 12 nodes. Searching with `regionId=211`, `catIds=[27011]` returned 3 samples (upstream `total=10000`); a subsequent detail query using the first `goodsId` returned a product object and 13 history records.
The examples below use successful live responses from 2026-08-27 to confirm field hierarchy. Business values are illustrative only; nullable business fields may be omitted.
## Product Fields (Search `items[]` / Detail `goods`)
| Field Group | Field |
|---|---|
| Identifiers and Text | `goodsId`, `mallId`, `thumbnail`, `goodsName`, `goodsNameCn`, `goodsNameEn`, `brand`, `sku` |
| Categories | `catIds`, `catItems` |
| Sales Volume and Stock | `sold`, `quantity`, `daySold`, `weekSold`, `monthSold`, `mallSold` |
| Monetary Values | `sales`, `minPrice`, `maxPrice`, `daySales`, `weekSales`, `monthSales` |
| Sales Volume Growth Rates | `daySoldRate`, `weekSoldRate`, `monthSoldRate` |
| Sales Revenue Growth Rates | `daySalesRate`, `weekSalesRate`, `monthSalesRate` |
| Supply Prices | `supplyPrice`, `minSupplyPrice`, `medianSupplyPrice`, `maxSupplyPrice` |
| Reviews | `goodsScore`, `reviewNum` |
| Status | `hostingMode`, `status`, `isAd`, `isCustom`, `isPresale` |
| Time | `onSaleTime`, `mallOpenTime`, `createTime`, `updateTime` |
| Other | `similarNum`, `extraFields` |
`catItems[]` contains `catId`, `catLevel`, `catName`, `isLeaf`, `parentCatId`, `extraFields`. Interpret monetary fields in the current site currency, except supply prices.
## Product Search: `POST /api/v1/tools/research/geekbi/temu/goodsSearch`
### Request
POST body (JSON). All fields are optional; an empty object `{}` uses `regionId=211`, `page=1`, `size=20`, `matchMode=2`.
#### Pagination, Matching, Categories, and Status
| Parameter | Type | Required | Default / Constraints | Description |
|---|---|---:|---|---|
| `regionId` | integer | No | `211`;`>=1` | Temu region ID; obtain it from `sites[].regionId` in the site list |
| `page` | integer | No | `1`;`>=1` | Page number |
| `size` | integer | No | `20`;`1..200` | Items per page; `page * size` must not exceed 10000 |
| `keyword` | string | No | Maximum 300 characters | Keyword matching product titles |
| `matchMode` | integer | No | `2`;`1..2` | `1`=strict matching, `2`=fuzzy matching |
| `catIds` | integer[] | No | - | Category ID array; obtain elements from `categories[].catId` in the category list |
| `status` | integer[] | No | Elements must be `1`, `2`, or `3` | `1`=normal, `2`=out of stock, `3`=delisted |
| `hostingMode` | integer | No | `1..2` | `1`=fully managed, `2`=semi-managed |
| `sort` | string | No | Maximum 100 characters | Sort field; use only fields confirmed to be supported by the endpoint |
| `order` | string | No | `asc` or `desc` | Sort direction, case-insensitive |
In gateway JSON, `catIds` and `status` must be arrays, e.g. `{"catIds":[984,982],"status":[1,2]}`. The server encodes each array as a single comma-separated upstream parameter; do not send comma-separated strings or duplicate keys in JSON.
#### Sales Volume, Revenue, and Growth Rates
| Parameter Group | Type | Constraints / Units |
|---|---|---|
| `soldMin`, `soldMax` | integer | Historical cumulative units sold, `>=0` |
| `daySoldMin`, `daySoldMax` | integer | Average daily units sold, `>=0` |
| `weekSoldMin`, `weekSoldMax` | integer | Average weekly units sold, `>=0` |
| `monthSoldMin`, `monthSoldMax` | integer | Average monthly units sold, `>=0` |
| `daySoldRateMin`, `daySoldRateMax` | number | Daily sales volume growth rate, percentage |
| `weekSoldRateMin`, `weekSoldRateMax` | number | Weekly sales volume growth rate, percentage |
| `monthSoldRateMin`, `monthSoldRateMax` | number | Monthly sales volume growth rate, percentage |
| `salesMin`, `salesMax` | number | Historical cumulative sales revenue in the current site currency, `>=0` |
| `daySalesMin`, `daySalesMax` | number | Average daily sales revenue in the current site currency, `>=0` |
| `weekSalesMin`, `weekSalesMax` | number | Average weekly sales revenue in the current site currency, `>=0` |
| `monthSalesMin`, `monthSalesMax` | number | Average monthly sales revenue in the current site currency, `>=0` |
| `daySalesRateMin`, `daySalesRateMax` | number | Daily sales revenue growth rate, percentage |
| `weekSalesRateMin`, `weekSalesRateMax` | number | Weekly sales revenue growth rate, percentage |
| `monthSalesRateMin`, `monthSalesRateMax` | number | Monthly sales revenue growth rate, percentage |
#### Prices, Stock, Shops, and Reviews
| Parameter Group | Type | Constraints / Units |
|---|---|---|
| `quantityMin`, `quantityMax` | integer | Remaining stock, `>=0` |
| `mallSoldMin`, `mallSoldMax` | integer | Shop historical cumulative units sold, `>=0` |
| `priceMin`, `priceMax` | number | Product price in the current site currency, `>=0` |
| `supplyPriceMin`, `supplyPriceMax` | number | Supply price in CNY, `>=0` |
| `goodsScoreMin`, `goodsScoreMax` | number | Product rating, `0..5` |
| `reviewNumMin`, `reviewNumMax` | integer | Historical cumulative review count, `>=0` |
#### Time Ranges
| Parameter Group | Type | Description |
|---|---|---|
| `onSaleTimeMin`, `onSaleTimeMax` | string | Product listing time range, ISO-8601 date-time, maximum 40 characters |
| `mallOpenTimeMin`, `mallOpenTimeMax` | string | Shop opening time range, ISO-8601 date-time, maximum 40 characters |
Every paired `*Min` must not exceed its corresponding `*Max`. Always use ISO-8601 date-time for time fields; the server parses and compares times only when both Min/Max in the same group are supplied. A single invalid time string may be rejected upstream.
#### curl Examples
```bash
curl -X POST "${NEXSCOPE_PROXY_BASE}/api/v1/tools/research/geekbi/temu/goodsSearch" \
-H "Authorization: Bearer $NEXSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-H "User-Agent: Nexscope-Skill/1.0" \
-H "SESSION_ID: ${SESSION_ID}" \
-H "MESSAGE_ID: ${MESSAGE_ID}" \
-H "MODE_ID: ${MODE_ID}" \
-H "APP_NAME: ${APP_NAME}" \
-d '{"regionId":211,"keyword":"dress","catIds":[984],"page":1,"size":20,"sort":"sold","order":"desc"}'
```
## Nexscope response envelope
These research endpoints return a platform object with numeric `code`, nullable `msg`, and business `data`. Only outer `code: 0` means success; `200`, string codes, missing codes, and HTTP 200 alone do not. A nonzero code is a platform error: show `msg` and do not interpret the payload as a successful result.
`msg` preserves the upstream message when available; Chinese messages are translated to English by Nexscope. A successful response without a message has `msg: null`. Do not infer success or retry behavior from the message text. On both success and failure, the direct fields `code`, `errcode`, `errorCode`, `msg`, `errmsg`, `message`, and `errorMsg` are removed from public `data`. Read the message only from outer `msg`; deeper business fields are preserved, including nested `code` and `status`.
Package scripts unwrap this platform object for their business output and retain its `code`, `msg`, and timing metadata under `_nexscope`; for those outputs, inspect `_nexscope.code` / `_nexscope.msg`. Business `code` or `error` fields are not platform success markers.
Business field tables and abbreviated business examples below describe `data`, unless explicitly labeled as a complete platform response. For example, a business `products` field is at HTTP `data.products`, and a business `data` array is at HTTP `data.data`. The research endpoints already had this outer envelope; no additional wrapper is added.
```json
{"code":0,"msg":null,"data":{}}
```
Metadata includes string `ts` (epoch milliseconds), string `cost` (elapsed milliseconds, not credits), `time`, and nullable `traceId`. Handle network/HTTP failures before the platform code; gateway failures may not be platform JSON. Keep the existing billing-header guidance separate from elapsed time.
### Response
| Field | Type | Description |
|---|---|---|
| `items` | array | Products on the current page; every business field may be absent or `null` |
| `columns` | array | Render column definitions |
| `total` | integer | Total matches reported upstream; the service limits only the accessible window to `page * size <= 10000` without truncating `total`; if absent upstream, falls back to the current `items` length |
| `page` | integer | Current page number |
| `size` | integer | Items per page |
| `regionId` | integer | Region ID used for this request |
| `title` | string | `Temu 数据查询` (Temu data query) |
| `sourceType` | string | `temu` |
| `sourceTool` | string | `geekbi_temu` |
| `type` | string | `tableListWorkbenches` |
#### Response Example
```json
{
"total": 1,
"page": 1,
"size": 20,
"regionId": 211,
"items": [
{
"goodsId": "601099512345678",
"goodsName": "Example product",
"catIds": [984],
"sold": 12,
"sales": 3.5
}
],
"columns": [],
"title": "Temu 数据查询",
"sourceType": "temu",
"sourceTool": "geekbi_temu",
"type": "tableListWorkbenches"
}
```
## Product Detail: `POST /api/v1/tools/research/geekbi/temu/goodsDetail`
### Request
| Parameter | Type | Required | Default / Constraints | Description |
|---|---|---:|---|---|
| `goodsId` | string | Yes | Nonempty; maximum 100 characters | Temu product ID, usually from search `items[].goodsId` |
| `regionId` | integer | No | `211`;`>=1` | Temu region ID; use the same value as in the search |
#### curl Examples
```bash
curl -X POST "${NEXSCOPE_PROXY_BASE}/api/v1/tools/research/geekbi/temu/goodsDetail" \
-H "Authorization: Bearer $NEXSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-H "User-Agent: Nexscope-Skill/1.0" \
-H "SESSION_ID: ${SESSION_ID}" \
-H "MESSAGE_ID: ${MESSAGE_ID}" \
-H "MODE_ID: ${MODE_ID}" \
-H "APP_NAME: ${APP_NAME}" \
-d '{"goodsId":"601099512345678","regionId":211}'
```
### Response
| Field | Type | Description |
|---|---|---|
| `goods` | object | Product object, with the same fields as search `items[]` |
| `history` | array | History records from the last 30 days; business fields may be absent or `null` |
| `regionId` | integer | Region ID used for this request |
| `title` | string | `Temu 商品详情` (Temu product detail) |
| `sourceType` | string | `temu` |
| `sourceTool` | string | `geekbi_temu` |
| `type` | string | `productWorkbenches` |
| `columns` | array | Product detail render columns |
#### Product History `history[]`
All history entry fields may be absent or `null`:
`id`, `sold`, `sales`, `minPrice`, `maxPrice`, `quantity`, `goodsScore`, `reviewNum`, `daySold`, `weekSold`, `monthSold`, `daySales`, `weekSales`, `monthSales`, `daySoldRate`, `weekSoldRate`, `monthSoldRate`, `daySalesRate`, `weekSalesRate`, `monthSalesRate`, `createTime`, `extraFields`。
#### Response Example
```json
{
"goods": {"goodsId": "601099512345678", "goodsName": "Example product"},
"history": [{"sold": 12, "sales": 3.5, "createTime": "2026-08-25T00:00:00Z"}],
"regionId": 211,
"title": "Temu 商品详情",
"sourceType": "temu",
"sourceTool": "geekbi_temu",
"type": "productWorkbenches",
"columns": []
}
```
## Site List: `POST /api/v1/tools/research/geekbi/temu/siteList`
### Request
No business parameters; send `{}` as the body. Use only nonempty positive-integer `sites[].regionId` for product search and detail; `sites[].siteId` is an upstream internal ID and must not replace `regionId`. If no valid `regionId` exists, stop chained calls and inform the user.
#### curl Examples
```bash
curl -X POST "${NEXSCOPE_PROXY_BASE}/api/v1/tools/research/geekbi/temu/siteList" \
-H "Authorization: Bearer $NEXSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-H "User-Agent: Nexscope-Skill/1.0" \
-H "SESSION_ID: ${SESSION_ID}" \
-H "MESSAGE_ID: ${MESSAGE_ID}" \
-H "MODE_ID: ${MODE_ID}" \
-H "APP_NAME: ${APP_NAME}" \
-d '{}'
```
### Response
| Field | Type | Description |
|---|---|---|
| `sites` | array | Supported Temu sites |
| `total` | integer | Site count |
| `title` / `sourceType` / `sourceTool` / `type` | string | `Temu 站点列表` (Temu site list) / `temu` / `geekbi_temu` / `tableListWorkbenches` |
| `columns` | array | Render column definitions |
`sites[]` fields: `siteId` (integer or string internal ID, not used for filtering), `regionId` (positive integer used by other endpoints), `name` (site name), `cnName` (Chinese name; the sample value means United States), `lang`, `currency`, and optional object `extraFields`. Business fields may be null; filter out empty `regionId` values before chained calls.
#### Response Example
```json
{
"sites": [{"siteId": 1, "regionId": 211, "name": "United States", "cnName": "美国", "lang": "en", "currency": "USD"}],
"total": 1,
"title": "Temu 站点列表",
"sourceType": "temu",
"sourceTool": "geekbi_temu",
"type": "tableListWorkbenches",
"columns": []
}
```
## Category List: `POST /api/v1/tools/research/geekbi/temu/categoryList`
### Request
| Parameter | Type | Required | Constraints | Description |
|---|---|---:|---|---|
| `parentCatId` | integer | No | `>=0` | Omit to return first-level categories; pass a `categories[].catId` to query its immediate children |
Category search dependency: first use `{}` to obtain first-level nodes. When drilling down, use only a nonempty nonnegative-integer `catId` as the next request's `parentCatId`; when filtering products, put only valid `catId` values in the product search `catIds` array. If no valid `catId` exists, stop chained calls and inform the user. Passing `0` is valid, but the source code does not establish equivalence with omitting `parentCatId`.
#### curl Examples
```bash
curl -X POST "${NEXSCOPE_PROXY_BASE}/api/v1/tools/research/geekbi/temu/categoryList" \
-H "Authorization: Bearer $NEXSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-H "User-Agent: Nexscope-Skill/1.0" \
-H "SESSION_ID: ${SESSION_ID}" \
-H "MESSAGE_ID: ${MESSAGE_ID}" \
-H "MODE_ID: ${MODE_ID}" \
-H "APP_NAME: ${APP_NAME}" \
-d '{"parentCatId":100}'
```
### Response
| Field | Type | Description |
|---|---|---|
| `categories` | array | Category nodes under the specified parent |
| `total` | integer | Number of returned nodes |
| `parentCatId` | integer / omitted | Parent ID for this query; observed first-level queries omit it, while queries specifying a parent return that ID |
| `title` / `sourceType` / `sourceTool` / `type` | string | `Temu 品类列表` (Temu category list) / `temu` / `geekbi_temu` / `tableListWorkbenches` |
| `columns` | array | Render column definitions |
`categories[]` fields: `catId`, `catName`, `catLevel`, `parentCatId`, `isLeaf`, `extraFields`. Business fields may be null; only nonempty valid `catId` values may be used for product search `catIds` or the next `parentCatId`.
#### Response Example
```json
{
"categories": [{"catId": 984, "catName": "Women Clothing", "catLevel": 2, "parentCatId": 100, "isLeaf": false}],
"total": 1,
"parentCatId": 100,
"title": "Temu 品类列表",
"sourceType": "temu",
"sourceTool": "geekbi_temu",
"type": "tableListWorkbenches",
"columns": []
}
```
## `columns[]` Structure
Each column definition usually contains `field`, `title`, `cellType`, `sortable`, `filterable`; `cellType` is `number` or `text`.
## Error Codes
HTTP 200 does not prove business success. Read only the numeric outer platform `code`: `0` succeeds and any other value fails. Show outer `msg`; never test removed provider codes or nested business `code` as the platform status. Authentication, permissions, balance, and validation failures may be platform errors even with HTTP 200; also handle non-2xx HTTP and non-JSON responses.
### Recovery guidance
| Condition | Action |
|---|---|
| Parameter validation failed | Correct fields according to the message; do not automatically change keywords, pages, or sites and retry repeatedly |
| Authentication failed | Check `NEXSCOPE_API_KEY` and follow the authentication guidance in `SKILL.md` |
| Insufficient compute credits or balance | Stop calling and follow the authentication/compute-credit guidance |
| Access denied | Stop calling and contact the tool administrator; do not treat this as a top-up issue |
| Too many requests | Stop repeated calls and try again later |
| Gateway or upstream error | Do not automatically retry paid search/detail calls; explain that another charge may occur and obtain user confirmation before retrying once with the original parameters. Free site/category helper endpoints may be retried 1–2 times with the original parameters |
The entry script retains the platform code and message on failures, with the original response available under `response`; it does not print Python stack traces for gateway errors.
Product search also rejects `regionId<1`, `page<1`, `size` outside 1–200, `page*size>10000`, invalid `status/hostingMode/order`, and any minimum exceeding its maximum. Null values in `catIds` are filtered out; null values in `status` are rejected. Callers should send only valid integers. Product detail rejects empty `goodsId` or invalid `regionId`; reuse only nonempty `items[].goodsId` from search results.
Legacy local cache: a still-valid cache created before this response contract remains usable without a new paid request. The scripts mark its copied metadata as `_nexscope.responseContract = "legacy-cache"`, with `_nexscope.code` and `_nexscope.msg` set to `null` because the original platform status/message is unavailable. Do not infer platform success from business `errcode`, `code`, or `status`. Existing business data, billing metadata, cache contents and expiration are preserved; the marker is added only to the in-memory output.
## API Key request rate and retries
All API Keys of one Nexscope user share the public API execution request-rate allowance, measured in any rolling 1-second window. The allowed RPS depends on that user's entitlements; it is not a universal 1 RPS. One Skill operation may issue multiple public API requests, each of which uses the allowance.
HTTP 429 with Nexscope outer code `13012` means request-rate exhaustion: honor the response's `Retry-After`. Outer code `13013` means concurrent-request exhaustion, not rate exhaustion; honor `Retry-After` when supplied. Check the HTTP status and outer JSON code separately. Do not automatically replay writes or requests with uncertain outcomes; first reconcile the operation's state.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |