Produkt-Keyword-Suche API

POST /v1/products/search — keyword search returning a paginated product list.

Taobao → upstream /traffic/item/search
1688 → upstream product.search.keywordQuery

Unsupported fields for a channel are silently ignored (no extra response headers).

Common request fields

Field	Required	Description
`channel`	Yes	`1688` \| `taobao`
`keyword`	Yes	Search term
`language`	No	Default `en`
`page` / `page_size`	No	Pagination (Taobao max 20 per page)
`response_format`	No	`standard` (default) or `upstream`
`sort_field`	No	`price` \| `sales` \| `credit` (`credit` is 1688-only; Taobao ignores)
`sort_order`	No	`asc` \| `desc` (default `asc`; use with `sort_field`)
`price_start` / `price_end`	No	Price range in yuan (decimals allowed, e.g. `19.9`)
`ship_within_hours`	No	`0` (same day) \| `24` \| `48`
`category_ids`	No	Comma-separated category IDs. 1688 only; Taobao ignores
`product_collection_id`	No	Business pool ID. 1688 only; Taobao ignores

Sort (`sort_field` + `sort_order`)

`sort_field`	`sort_order`	→ 1688	→ Taobao
`price`	`asc` / `desc`	`{"bid":"asc\|desc"}`	`PRICE_ASC` / `PRICE_DESC`
`sales`	`asc` / `desc`	`{"sale":"asc\|desc"}`	`SALE_QTY_ASC` / `SALE_QTY_DESC`
`credit`	`asc` / `desc`	`{"credit":"asc\|desc"}`	Ignored

Legacy aliases for sort_field: bid → price, sale → sales.

Price

Gateway always uses yuan (decimals OK).
1688 → priceStart / priceEnd.
Taobao → filters min_price / max_price in fen (Math.round(yuan * 100)).

Shipping (`ship_within_hours`)

Value	→ 1688 `filter`	→ Taobao `filters`
`0`	`shipInToday`	Ignored
`24`	`shipIn24Hours`	`24shipping`
`48`	`shipIn48Hours`	`48shipping`

1688-only filters (Taobao ignores)

Field	Type	Description
`experience_score_level`	integer	`1`…`4` → `totalEpScoreLv1`…`Lv4`
`product_attrs`	string	Comma-separated: `isOnePsale`, `isOnePsaleFreePost`, `new7`, `new30`, `1688Selection`, `isQqyx`
`filter`	string	Advanced comma-separated tags; merged with semantic fields above
`sale_filters`	object[]	Maps to `saleFilterList` (`sale_type`: `sales7` \| `sales14` \| `sales30` \| `totalSales`, optional `sale_start` / `sale_end`)
`keyword_translate`	boolean	Whether the keyword is already translated

Deprecated aliases: category_id, category_id_list (prefer category_ids).

Examples

1688

POST /v1/products/search
{
  "channel": "1688",
  "keyword": "phone case",
  "language": "en",
  "page": 1,
  "page_size": 20,
  "sort_field": "sales",
  "sort_order": "desc",
  "price_start": 10.5,
  "price_end": 99.9,
  "ship_within_hours": 24,
  "experience_score_level": 2,
  "product_attrs": "isOnePsale,1688Selection",
  "filter": "noReason7DReturn",
  "category_ids": "123,456",
  "product_collection_id": "262105288"
}

Taobao

POST /v1/products/search
{
  "channel": "taobao",
  "keyword": "帽子",
  "language": "en",
  "page": 1,
  "page_size": 20,
  "sort_field": "price",
  "sort_order": "asc",
  "price_start": 20,
  "price_end": 100,
  "ship_within_hours": 24
}

Response

StandardProductList — summary cards in items[]. Call product detail for full SKU matrix and stock.

With response_format: "upstream", the response is the channel vendor payload wrapped by HIOBuy (see Response format).