# Taobao & Tmall Scraper - $1.50 / 1000 Products (`scrapeunblocker/taobao-scraper`) Actor

Taobao and Tmall products as clean JSON: search by keyword (Chinese or English) or category, or read item pages by link or id. Price in yuan with local prices, shop and its service scores, rating split, latest review, category path and ship-from location. No login. $1.50 per 1000 products.

- **URL**: https://apify.com/scrapeunblocker/taobao-scraper.md
- **Developed by:** [Scrapeunblocker](https://apify.com/scrapeunblocker) (community)
- **Stats:** 1 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.50 / 1,000 products

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Taobao & Tmall Scraper

Scrape **Taobao and Tmall** products as clean, structured JSON - search by **keyword** (Chinese or English) or **category**, or read **item pages** from links or ids. Every product comes with its **title**, **price in yuan** plus local prices (SGD, HKD, TWD), **shop** and Taobao's price tag. Item pages add the **ship-from location**, **category path**, **buyer rating split**, the **latest review** with its photos and videos, and the **shop's service scores, credit level and opening date**. Taobao and Tmall links both work. No Taobao account, cookies or proxies to set up.

### Features

- **Keyword search** - the first page Taobao shows for a keyword (up to 20 products), in Taobao's order (`position`), sorted by relevance, best selling or price.
- **Price filter** - a minimum and maximum price in yuan.
- **Categories** - the top 20 best sellers of any Taobao category, by id or link.
- **Item pages** - Taobao and Tmall item links (item.taobao.com, detail.tmall.com, world.taobao.com) or bare item ids.
- **Prices you can compute with** - `price` as a number in CNY, with `localPrices` in SGD, HKD and TWD.
- **Shop quality** - shop name and id, and on item pages the shop's description, service and delivery scores, credit level, seller type and opening date.
- **Buyer feedback** - on item pages the positive / neutral / negative split with counts, and the latest review (stars, text, date, variant bought, photos and videos). No reviewer names are returned.
- **Keyword fallback** - when Taobao has no results page for a keyword, the closest keyword Taobao itself suggests is used, and the items say so (`keywordSubstituted`, `matchedKeyword`, `notice`).
- **Deduplicated inputs** - the same keyword, category or item given twice is fetched and billed once.

### Use cases

- **Sourcing and dropshipping** - find products and check a shop's scores, credit level and age before ordering.
- **Price research** - compare prices across keywords and categories, in yuan and local currencies.
- **Price monitoring** - track the price of a list of Taobao and Tmall items on a schedule.
- **Best-seller tracking** - follow the top products of a category or keyword over time.
- **Market analysis** - listing counts per keyword and category, price ranges, Tmall vs Taobao shops.

### Input

Give any mix of searches, categories and product links.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `searches` | array | - | Keywords, in Chinese or English (one search each, up to 20 products). |
| `categories` | array | - | Taobao category ids or category links (top 20 best sellers each). |
| `productUrls` | array | - | Taobao or Tmall item links or item ids (one item page each). |
| `sort` | string | `relevance` | Order of keyword searches: `relevance`, `sales`, `price_asc`, `price_desc`. |
| `priceMin` | integer | - | Keyword searches only: minimum price in yuan. |
| `priceMax` | integer | - | Keyword searches only: maximum price in yuan. |
| `concurrency` | integer | `3` | Inputs fetched at the same time (1-5). |

With no input at all, the actor searches the example keyword `手机壳` (phone case).

#### Example input

```json
{
  "searches": ["蓝牙耳机", "phone case"],
  "categories": ["50005050"],
  "productUrls": [
    "https://item.taobao.com/item.htm?id=765833709683",
    "https://detail.tmall.com/item.htm?id=1081364414020"
  ],
  "sort": "sales",
  "priceMin": 100,
  "priceMax": 300
}
```

### Output

One dataset item per product. From a search (`source: "search"`) or a category (`source: "category"`, with `category` instead of `query`):

```json
{
  "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": [],
  "source": "search",
  "sort": "relevance",
  "totalResults": 32036,
  "query": "手机壳"
}
```

When Taobao has no results page for a keyword, its items carry the substitute:

```json
{
  "query": "防水运动蓝牙耳机跑步专用挂耳式",
  "keywordSubstituted": true,
  "matchedKeyword": "运动防水蓝牙耳机",
  "notice": "Taobao has no list for '防水运动蓝牙耳机跑步专用挂耳式'; these are the results for its suggested keyword '运动防水蓝牙耳机'."
}
```

From a product link (`source: "product"`, shortened):

```json
{
  "itemId": "765833709683",
  "url": "https://item.taobao.com/item.htm?id=765833709683",
  "platform": "taobao",
  "title": "真无线蓝牙5.5耳机 ANC主动降噪高音质 2025新款五代顶配 杜比环绕音效 超长续航IPX5防水",
  "titleTruncated": false,
  "price": 388.0,
  "priceMax": null,
  "originalPrice": 388.0,
  "currency": "CNY",
  "hasPriceRange": false,
  "priceNote": "价格可能因优惠活动发生变化",
  "image": "https://img.alicdn.com/imgextra/i3/2523443838/O1CN01QULkBg1eDrFVYcid7_!!2523443838.jpg",
  "location": "广东深圳",
  "categoryId": "50005050",
  "categoryPath": ["影音视听", "耳机耳放", "耳机"],
  "freeShipping": false,
  "paymentMethods": ["蚂蚁花呗", "集分宝", "支付宝支付"],
  "rating": {
    "positivePercent": 98,
    "neutralPercent": 2,
    "negativePercent": 0,
    "positiveCount": 70000,
    "positiveCountText": "7万+",
    "negativeCount": 500,
    "negativeCountText": "500+"
  },
  "latestReview": {
    "rating": 5,
    "content": "很好用声音很清晰，很好用，很推荐材质也非常得好。续航能力也很好。",
    "date": "2026-10-18T06:10:00Z",
    "variant": "颜色分类:【Pro3代至尊版】超宽频ANC主动降噪★智能触控零延迟★全功能还原",
    "images": [],
    "videos": [
      {
        "url": "https://cloud.video.taobao.com/play/u/null/p/1/d/hd/e/6/t/1/921795906106422.mp4",
        "cover": "https://img.alicdn.com/imgextra/i4/O1CN01zxyvWsUqn3J1SdfM_!!4611686018427386076-0-rate.jpg"
      }
    ]
  },
  "shop": {
    "shopId": "467290190",
    "name": "深圳华强北正品直销总店",
    "url": "https://shop467290190.taobao.com",
    "sellerType": "C",
    "creditLevel": 17,
    "openedAt": "2019-08-05T16:41:09Z",
    "itemCount": 20,
    "newItemCount": 1,
    "scores": {"delivery": 4.8, "service": 4.8, "description": 4.7}
  },
  "shopId": "467290190",
  "shopName": "深圳华强北正品直销总店",
  "source": "product",
  "input": "https://item.taobao.com/item.htm?id=765833709683"
}
```

Item pages also carry `images`, `rootCategoryId`, `areaLimit`, `sellableLanguages`, the shop's `logo`, and `followUps` on a review (a buyer's later comment with photos). `sellerType` is `B` for Tmall stores and `C` for Taobao stores. Dates are ISO 8601 in UTC.

Searches, categories and product links that return nothing or cannot be read go to the `ERRORS` record in the run's key-value store, with the reason (for example an item Taobao no longer shows, or a keyword with no results page and no usable suggestion). They are not billed.

### Pricing

**$1.50 per 1000 products** (pay per result) - one dataset item is one product, from a search, a category or a product link. A product link is read from its own item page, so each product from `productUrls` also counts one `product-details` event at **$1.50 per 1000** (a product page costs $3 per 1000 in total). Failed inputs are free.

### Notes

- A keyword search returns one page of up to 20 products: that is all Taobao shows visitors who are not logged in. For more products, split a search into narrower keywords or price bands, or add the matching categories.
- The price filter keeps only products whose listed price is in the range, so a search may return fewer than 20.
- Variants (SKUs), stock and monthly sales need a Taobao login and are not included.
- Tmall item pages show a shortened title (`titleTruncated`) and no rating split; search results always carry the full title.
- Prices are those Taobao shows; coupons and app-only discounts are not applied.
- Titles, labels and reviews come in Chinese as sellers and buyers write them.
- Taobao share links (e.tb.cn, m.tb.cn) open only in the Taobao app; use the item link or id instead.
- Powered by [ScrapeUnblocker](https://www.scrapeunblocker.com).

# Actor input Schema

## `searches` (type: `array`):

Keywords to search on Taobao (one search each), in Chinese or English, e.g. '手机壳' or 'phone case'. Chinese keywords match far more listings. Each search returns the first page Taobao shows signed-out visitors: up to 20 products. When Taobao has no results page for a keyword, the closest keyword Taobao itself suggests is used and the items say so.

## `categories` (type: `array`):

Taobao category ids (e.g. 50005050) or category links (https://www.taobao.com/list/category/50005050.htm). Each returns the category's top 20 best sellers. Leave empty to use only searches or product links.

## `productUrls` (type: `array`):

Taobao or Tmall item links (https://item.taobao.com/item.htm?id=..., https://detail.tmall.com/item.htm?id=..., world.taobao.com/item/<id>.htm) or bare item ids. Each returns the item page: title, price, ship-from location, category path, rating split, latest review and the shop with its service scores. Leave empty to use only searches or categories.

## `sort` (type: `string`):

The order keyword searches are taken in, which decides which 20 products you get. Categories always come in best-seller order.

## `priceMin` (type: `integer`):

Keyword searches only: only products at or above this price in yuan (CNY).

## `priceMax` (type: `integer`):

Keyword searches only: only products at or below this price in yuan (CNY).

## `concurrency` (type: `integer`):

How many searches, categories or product pages to fetch at the same time (1-5).

## Actor input object example

```json
{
  "searches": [
    "手机壳"
  ],
  "sort": "relevance",
  "concurrency": 3
}
```

# Actor output Schema

## `results` (type: `string`):

One item per product: price in yuan with local prices, shop, and for product pages the rating split, latest review and shop scores

## `errors` (type: `string`):

Searches, categories and product links that returned nothing or could not be read, with the reason (not billed)

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "searches": [
        "手机壳"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("scrapeunblocker/taobao-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "searches": ["手机壳"] }

# Run the Actor and wait for it to finish
run = client.actor("scrapeunblocker/taobao-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "searches": [
    "手机壳"
  ]
}' |
apify call scrapeunblocker/taobao-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,scrapeunblocker/taobao-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/X0AVgf6oOEswd1ug7/builds/huwXkehpuE7NmtBgf/openapi.json