Product Search

Search products on supported marketplaces (Taobao, 1688) with pagination.

POSThttps://open.hiobuy.com/api/client/third-purchase/search

If your deployment uses a different base URL, replace `https://open.hiobuy.com` accordingly.

Request headers

Name	Required	Type	Description
`X-Uuid`	Yes	string	Merchant UUID assigned to your account
`Language`	No	string	Locale for product titles and attributes. Default: `zh_CN`. See supported locales.

Supported locales

Marketplace	Code	Locale
Taobao	`zh_CN`	Chinese
Taobao	`en_US`	English
Taobao	`vi_VN`	Vietnamese
1688	`zh_CN`	Chinese
1688	`en_US`	English
1688	`ko_KR`	Korean
1688	`ja`	Japanese
1688	`ru_RU`	Russian
1688	`vi_VN`	Vietnamese
1688	`es_ES`	Spanish
1688	`ar`	Arabic

Request body

Name	Required	Type	Description
`keyword`	Yes	string	Search keyword
`platform`	Yes	string	Marketplace code: `taobao` (Taobao), `1688` (1688.com)
`page`	No	string	Page index, starting at `1`. Default: `1`
`page_size`	No	string	Page size. Default: `20`
`use_platform`	No	string	Whether to use 1688 platform-native response fields. `0` = off, `1` = on. 1688 only. See 1688 API reference.
`sort`	No	string	Sort: `bid2` price descending; `bid` price ascending; `sale2` sales descending; `sale` sales ascending
`priceStart`	No	string	Minimum price (inclusive)
`priceEnd`	No	string	Maximum price (inclusive)
`filter`	No	array	Search filters (1688 only). See 1688 filter reference.

Example request

{
  "keyword": "handbag",
  "platform": "1688",
  "page": "1",
  "page_size": "20",
  "sort": "sale2",
  "priceStart": "100",
  "priceEnd": "800"
}

Sample response

{
  "ret": 1,
  "msg": "Success",
  "data": {
    "api_type": "taobao",
    "items": {
      "item": [
        {
          "detail_url": "https://item.taobao.com/item.htm?id=877698299628",
          "num_iid": 877698299628,
          "pic_url": "https://img.alicdn.com/imgextra/i3/2635590370/O1CN019Q9JFb1EbVZzd609G_!!4611686018427382498-0-item_pic.jpg",
          "price": "680.00",
          "sales": 0,
          "title_cn": "On My Level 女士小款手袋丨lululemon丨LW9FNDS",
          "title": "On My Level Women's Small Handbag丨Lululemon丨Lw9Fnds",
          "seller_nick": "lululemon官方旗舰店",
          "tags": [],
          "quantity": 200
        }
      ],
      "total_results": 1000
    }
  }
}

Response fields

Top level

Name	Type	Description
`ret`	number	Status code. `1` indicates success
`msg`	string	Status message
`data`	object	Response body

`data.items.item[]`

Name	Type	Description
`detail_url`	string	Product detail page URL
`num_iid`	integer	Marketplace product ID
`pic_url`	string	Main image URL
`price`	string	Unit price
`sales`	integer	Units sold (cumulative)
`title_cn`	string	Chinese title
`title`	string	Localized title (per `Language` header)
`seller_nick`	string	Seller shop name (image search may return a trace ID; use shop-nick when you have `shop_id`)
`tags`	array	Product tags
`quantity`	integer	Available stock

Pagination

Name	Type	Description
`data.items.total_results`	integer	Total number of matched products