Elimapi

How to search products on Taobao/1688

When to use this guide

Use this guide when you need product data from Taobao/1688: search by keyword or image, apply filters, and get product details.

This guide uses the Product API v2 (current version). If you are using v1, see Product API v1 (Legacy).

Full reference for every parameter and value: Product API reference

Prerequisites

Search by keyword

Step 1 — Call the search endpoint

POST /v2/products/search

{
  "platform": "taobao",
  "q": "áo thun cotton",
  "page": 1,
  "size": 20,
  "lang": "vi"
}

The platform parameter (taobao or alibaba) is required in API v2.

Step 2 — Translate results

Use the lang parameter (vi/en/ru/ko/ja) to receive translated titles. Translated data is in the title_en key; the title key remains the original Chinese.

Step 3 — Sort results

Use the sort parameter:

ValueMeaning
PRICE_ASC / PRICE_DESCPrice ascending/descending
SALE_QTY_ASC / SALE_QTY_DESCSales quantity ascending/descending

Step 4 — Filter results (optional)

Use the filter parameter (most criteria apply to 1688 only):

  • filter.priceRange — price range (CNY): { "min": 0, "max": 100 } — ✅ Taobao ✅ 1688
  • filter.shopId — products from the same seller — ✅ Taobao ✅ 1688
  • filter.sellerLevel (L1–L4) — seller level
  • filter.isFactory — super factory products only
  • filter.ffmOutbound (FFMO1–FFMO6) — fast outbound rate
  • filter.ffmDelivery (FFMD0–FFMD2) — delivery speed
  • filter.allowDropship, filter.freeshipForDropship — dropship support
  • filter.newArrival (7DAY/30DAY) — newly updated products
  • filter.platformPick, filter.globalPick, filter.dropshipPick — platform-selected sources

Complete list of filter values: Product API reference

Search by image

Note: This feature does not apply to the Free plan.

POST /v2/products/search-by-image

There are 2 ways:

Option 1 — Image URL (only *.alicdn.com links):

{
  "platform": "taobao",
  "imgUrl": "https://img.alicdn.com/bao/uploaded/i3/694223667/O1CN01zSjKgp1cxXRQZsDLA_!!694223667.jpg",
  "lang": "vi"
}

Option 2 — Uploaded image:

  1. Upload the image via the POST /v2/products/upload-image API to get an imageId.
  2. Call search-by-image with imgId instead of imgUrl:
{
  "platform": "alibaba",
  "imgId": "image-123",
  "lang": "vi"
}

Get product details

Step 1 — Expand short links (if any)

Short links like https://e.tb.cn/h.hPY04k4RPfAco8F?tk=0CCI430IUqd must be expanded first. Use the Unshorten link API to get the original link and product ID.

Step 2 — Call the detail endpoint

POST /v2/products/find

{
  "platform": "taobao",
  "id": "734467086498"
}

The response includes: price, stock, variants (color/size), image album, description, and shipping policy. For fuller 1688 data, use POST /v2/products/detail with the same request structure.

Step 3 — Display prices correctly

  • Taobao: prefer promotion_price; if absent, use price.
  • 1688: price logic depends on quote_type (direct/by_sku/by_volume).

[!WARNING] API prices can be higher than the price on the Taobao/1688 website because the API cannot apply complex promotions. Warn your customers if you display prices on an extension/web/app.

Verify the result

  • The request returns HTTP 200 with a product array containing title, price, img_url.
  • Image search returns products similar to the original image.