> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scrapeunblocker.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Taobao & Tmall plugin

> Taobao and Tmall data as clean JSON - keyword or category listings with yuan prices, shop and description score, brand and property filters, plus one item with the buyer rating split, latest review and shop scores.

The **Taobao & Tmall** plugin returns listings from Taobao and Tmall, Alibaba Group's consumer marketplaces in China, as structured JSON. It is two endpoints:

* **`/marketplace/taobao-search`** - the products Taobao lists for a keyword (Chinese or English) or a category: item id, title, link and image, the price in yuan with Taobao's price tag (such as a discount price) and the same price in local currencies, the shop and its description score, free shipping, category ids, selling points and review highlights, plus Taobao's count of matching listings and the brand and property filters you can apply next.
* **`/marketplace/taobao-product`** - one Taobao or Tmall item: the platform, title, price, original price and price range in yuan, image, ship-from location, category path, free shipping, payment methods, the buyer rating split (Taobao items only), the latest review (stars, text, date and variant, no reviewer identity) and the shop with its seller type, credit level, opening date, item count and description, service and delivery scores.

The plugin reads the public catalogue Taobao publishes for signed-out visitors, so no Taobao login is involved, and what Taobao shows only after a login is not included: SKUs (variants), stock and monthly sales. Taobao shows signed-out visitors the first 20 products of a list, so one search returns up to 20; narrow it with a price range or a filter to reach other products. Text comes back in Chinese, as sellers write it, and prices are in yuan (CNY). For wholesale prices, see the [1688 plugin](/plugins/1688.md).

> [!NOTE]
>
> Try it in the dashboard first: [app.scrapeunblocker.com/dashboard/plugins](https://app.scrapeunblocker.com/dashboard/plugins). You get a live results view plus a copy-paste snippet.

## Search

```
POST /marketplace/taobao-search
```

| Field | Required | Notes |
| - | - | - |
| `q` | one of `q` / `category` | Keyword, in Chinese or English, e.g. `手机壳`, `连衣裙` or `phone case`. Chinese keywords match far more listings. A Taobao search or list link works too. |
| `category` | one of `q` / `category` | A Taobao category id, e.g. `50005050`, or a category list link (`https://www.taobao.com/list/category/50005050.htm`). Returns the category's best sellers; sort and filters apply to keyword searches only. |
| `sort` | no | `relevance` (default), `sales`, `price_asc` or `price_desc`. |
| `price_min` / `price_max` | no | Only products priced within this range, in yuan (CNY). Products whose listed price falls outside it are left out and counted in `droppedOutsidePriceRange`. |
| `filter` | no | One brand or property filter: the `filter` value of an option in `filterOptions` of an earlier answer, e.g. `20000-88634403`. |

```bash cURL theme={null}
curl -X POST "https://api.scrapeunblocker.com/marketplace/taobao-search?q=%E6%89%8B%E6%9C%BA%E5%A3%B3&sort=sales" \
  -H "x-scrapeunblocker-key: YOUR_API_KEY"
```

```python Python theme={null}
from scrapeunblocker import Client

su = Client()  # reads SCRAPEUNBLOCKER_KEY

result = su.taobao_search("手机壳", sort="sales")
```

```ts Node.js theme={null}
import { ScrapeUnblockerClient } from "scrapeunblocker";

const su = new ScrapeUnblockerClient(); // reads SCRAPEUNBLOCKER_KEY

const result = await su.taobaoSearch("手机壳", { sort: "sales" });
```

```php PHP theme={null}
use ScrapeUnblocker\Client;

$su = new Client(); // reads SCRAPEUNBLOCKER_KEY

$result = $su->taobaoSearch('手机壳', ['sort' => 'sales']);
```

```ruby Ruby theme={null}
require "scrapeunblocker"

su = ScrapeUnblocker::Client.new # reads SCRAPEUNBLOCKER_KEY

result = su.taobao_search("手机壳", sort: "sales")
```

To list a category, leave the keyword out and pass `category`, e.g. `su.taobao_search(category="50005050")` in Python. Each call that returns products is billed as one request; `404` and `502` are not billed.

When Taobao has no public list for a keyword, the call answers with the list of the closest keyword Taobao itself suggests and says so: `keywordSubstituted` is `true` and `matchedKeyword` is the keyword whose products you got. Check it before you treat the products as matches for your keyword.

### Response

```json theme={null}
{
  "query": { "q": "手机壳", "category": null, "sort": "sales", "priceMin": null, "priceMax": null, "filter": null },
  "matchedKeyword": "手机壳",
  "keywordSubstituted": false,
  "source": "sg.world.taobao.com",
  "sort": "sales",
  "currency": "CNY",
  "localCurrency": "SGD",
  "totalResults": 59084,
  "resultsCollected": 20,
  "products": [
    {
      "position": 1,
      "itemId": "1078907312106",
      "title": "【新款18勃艮第红色】图拉斯雪雾适用iPhone18ProMax手机壳苹果17磁吸外壳16pm高级磨砂15Pro保护套14P全包13",
      "url": "https://item.taobao.com/item.htm?id=1078907312106",
      "image": "https://img.alicdn.com/imgextra/O1CN01MD26uLjX8UC1chua_!!6000000000818-2-yinhe.png",
      "price": 116.0,
      "currency": "CNY",
      "priceLabel": "优惠价",
      "localPrices": [
        { "currency": "SGD", "price": 22.53 },
        { "currency": "HKD", "price": 137.73 },
        { "currency": "TWD", "price": 572.08 }
      ],
      "shopId": "72104903",
      "shopName": "图拉斯数码旗舰店",
      "descriptionMatchScore": 4.76,
      "freeShipping": false,
      "areaLimit": false,
      "categoryId": "150704",
      "rootCategoryId": "50008090",
      "sellingPoints": [],
      "reviewHighlights": []
    },
    {
      "position": 2,
      "itemId": "971278517006",
      "title": "绿联适用苹果iPhone18Promax磁吸手机壳17pro透明duo全包+16pm保护套新款15超薄散热14magsafe镜头13安全防摔",
      "url": "https://item.taobao.com/item.htm?id=971278517006",
      "image": "https://img.alicdn.com/imgextra/O1CN01pyIQGB0WC2I1chua_!!6000000001904-2-yinhe.png",
      "price": 54.9,
      "currency": "CNY",
      "priceLabel": "优惠价",
      "localPrices": [
        { "currency": "SGD", "price": 10.66 },
        { "currency": "HKD", "price": 65.18 },
        { "currency": "TWD", "price": 270.75 }
      ],
      "shopId": "67095450",
      "shopName": "绿联数码旗舰店",
      "descriptionMatchScore": 4.87,
      "freeShipping": false,
      "areaLimit": false,
      "categoryId": "150704",
      "rootCategoryId": "50008090",
      "sellingPoints": ["强磁吸附AI拍照键抗发黄"],
      "reviewHighlights": []
    }
  ],
  "filterOptions": [
    {
      "name": "品牌",
      "propertyId": "20000",
      "options": [
        { "name": "Nohon/诺希", "filter": "20000-88634403", "count": 2 },
        { "name": "以诺", "filter": "20000-6766802", "count": 2 }
      ]
    }
  ]
}
```

| Field | Notes |
| - | - |
| `matchedKeyword` / `keywordSubstituted` | The keyword whose list was returned, and `true` when it is Taobao's suggestion instead of `q`. |
| `totalResults` | How many listings Taobao reports for the keyword. |
| `products[].itemId` / `url` | Taobao item id and link. Pass the id to [Item](#item). |
| `products[].title` / `image` | Title (Chinese) and image. |
| `products[].price` / `currency` / `priceLabel` | Price in yuan (`CNY`) and Taobao's price tag, e.g. `优惠价` (discount price). |
| `products[].localPrices` | The same price in the storefront's currencies (`SGD`, `HKD`, `TWD`). |
| `products[].shopId` / `shopName` / `descriptionMatchScore` | The shop and its score for how well items match their descriptions. |
| `products[].freeShipping` / `categoryId` / `rootCategoryId` | Free shipping flag and category ids. |
| `products[].sellingPoints` / `reviewHighlights` | The selling points and review highlights Taobao shows on the card. |
| `filterOptions` | Brand and property facets: `name`, `propertyId` and `options` with `name`, `filter` and, for some, a `count`. Pass an option's `filter` back as `filter`. |
| `droppedOutsidePriceRange` | With a price range: how many products were left out because their listed price fell outside it. |
| `source` / `localCurrency` | Which Taobao catalogue answered, and its local currency. |

## Item

```
POST /marketplace/taobao-product
```

| Field | Required | Notes |
| - | - | - |
| `item_id` | one of `item_id` / `url` | Numeric Taobao or Tmall item id, e.g. `765833709683` (the `id` in `item.taobao.com/item.htm?id=...`). |
| `url` | one of `item_id` / `url` | Taobao or Tmall item link, e.g. `https://item.taobao.com/item.htm?id=765833709683` or `https://detail.tmall.com/item.htm?id=1081364414020`. world.taobao.com, mobile and overseas item links work too. |

```bash cURL theme={null}
curl -X POST "https://api.scrapeunblocker.com/marketplace/taobao-product?item_id=971278517006" \
  -H "x-scrapeunblocker-key: YOUR_API_KEY"
```

```python Python theme={null}
from scrapeunblocker import Client

su = Client()  # reads SCRAPEUNBLOCKER_KEY

result = su.taobao_product("971278517006")
```

```ts Node.js theme={null}
import { ScrapeUnblockerClient } from "scrapeunblocker";

const su = new ScrapeUnblockerClient(); // reads SCRAPEUNBLOCKER_KEY

const result = await su.taobaoProduct("971278517006");
```

```php PHP theme={null}
use ScrapeUnblocker\Client;

$su = new Client(); // reads SCRAPEUNBLOCKER_KEY

$result = $su->taobaoProduct('971278517006');
```

```ruby Ruby theme={null}
require "scrapeunblocker"

su = ScrapeUnblocker::Client.new # reads SCRAPEUNBLOCKER_KEY

result = su.taobao_product("971278517006")
```

To pass a link instead of an id, use the `url` option, e.g. `su.taobao_product(url="https://item.taobao.com/item.htm?id=765833709683")` in Python. An item is billed as one request; a removed item, or one Taobao does not show signed-out visitors, returns `404` and is not billed.

### Response

```json theme={null}
{
  "query": { "itemId": "971278517006" },
  "product": {
    "itemId": "971278517006",
    "url": "https://detail.tmall.com/item.htm?id=971278517006",
    "platform": "tmall",
    "title": "绿联适用苹果iPho...",
    "titleTruncated": true,
    "price": 52.8,
    "priceMax": null,
    "originalPrice": 52.8,
    "currency": "CNY",
    "hasPriceRange": false,
    "priceNote": "价格可能因优惠活动发生变化",
    "image": "https://img.alicdn.com/imgextra/O1CN01pyIQGB0WC2I1chua_!!6000000001904-2-yinhe.png",
    "images": ["https://img.alicdn.com/imgextra/O1CN01pyIQGB0WC2I1chua_!!6000000001904-2-yinhe.png"],
    "location": "广东深圳",
    "categoryId": "150704",
    "rootCategoryId": "50008090",
    "categoryPath": ["阿里B2C商城", "手机及配件", "手机配件", "保护套/硅胶套"],
    "freeShipping": false,
    "areaLimit": false,
    "paymentMethods": ["蚂蚁花呗", "信用卡支付", "集分宝"],
    "sellableLanguages": ["en_US"],
    "rating": null,
    "latestReview": {
      "rating": 5,
      "content": "刷小红书看到好多人推这种透明磁吸壳，就买了个康宁抗菌的试试。我手容易出汗，以前透 ...",
      "date": "2026-10-11T12:18:00Z",
      "variant": "适用手机型号:iPhone 17;颜色分类:【全透明·AI按键】24小时抗菌★康 ...",
      "hasMedia": false
    },
    "shop": {
      "shopId": "67095450",
      "name": "绿联数码旗舰店",
      "url": "https://shop67095450.taobao.com",
      "logo": "https://img.alicdn.com/imgextra//d2/82/TB1rBsXkkL0gK0jSZFASuwA9pXa.jpg",
      "sellerType": "B",
      "creditLevel": 20,
      "openedAt": "2011-05-30T06:37:22Z",
      "itemCount": 1332,
      "newItemCount": 29,
      "scores": { "delivery": 4.9, "service": 4.8, "description": 4.8 }
    }
  },
  "source": "www.taobao.com"
}
```

| Field | Notes |
| - | - |
| `platform` | `taobao` or `tmall`. |
| `title` / `titleTruncated` | The title, and `true` when Taobao shortens it, as it does for Tmall items. |
| `price` / `originalPrice` / `priceMax` / `hasPriceRange` / `currency` | Price in yuan, the price before a promotion, and the top of the range when the item has one. |
| `priceNote` | Taobao's note on the price, e.g. that it can change with promotions. |
| `image` / `images` | Item images. |
| `location` | Where the item ships from. |
| `categoryId` / `rootCategoryId` / `categoryPath` | Category ids and the category path. |
| `freeShipping` / `paymentMethods` | Free shipping flag and the payment methods Taobao lists. |
| `rating` | The buyer rating split: `positivePercent`, `neutralPercent`, `negativePercent`, `positiveCount` and `negativeCount`, with the count text Taobao shows. Taobao items only: Tmall does not publish it, so it is `null` there. |
| `latestReview` | The newest review: `rating` (stars), `content`, `date`, the `variant` bought, `hasMedia`, and `followUps` (later additions with `daysAfterReview`) when there are any. No reviewer identity, so no review photo or video URLs. |
| `shop` | `shopId`, `name`, `url`, `logo`, `sellerType` (`B` = Tmall, `C` = Taobao), `creditLevel`, `openedAt`, `itemCount`, `newItemCount` and `scores` for description, service and delivery. |

## Errors

| Status | Meaning |
| - | - |
| `400` | Invalid parameters, e.g. neither `q` nor `category`, an unknown `sort`, or a missing `item_id` / `url`. |
| `404` | Taobao has no public list for the keyword (nor for any keyword it suggests instead), the category or the filters, or no public page for the item. Not billed. |
| `502` | Taobao refused every attempt, or did not answer in time. Not billed; retry. |

## What you can build

* **Cross-border sourcing** - find consumer products and shops on Taobao and Tmall with yuan prices.
* **Price comparison** - compare Taobao prices with [1688](/plugins/1688.md), [AliExpress](/plugins/aliexpress.md) and retail prices for the same item.
* **Shop vetting** - compare shops by seller type, credit level, age and service scores.
* **Trend research** - see what sells for a keyword with `sort=sales`.

## Next steps

> **[Open the plugins](https://app.scrapeunblocker.com/dashboard/plugins)**
>
> Run a Taobao search and grab the JSON.

> **[Get an API key](https://scrapeunblocker.com/pricing)**
>
> Free trial available on the pricing page.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.