# Taobao Tmall 淘宝 Product Scraper - Prices, Sales & Shops (`clover_folktale/taobao-scraper`) Actor

Search Taobao and Tmall (淘宝/天猫) products by keyword and get price, discount price, sales count, shop name and ID, shop ratings, seller level, ship-from location, stock and images. Filter by price range or Tmall only. No login or cookies needed. Export to JSON, CSV or Excel.

- **URL**: https://apify.com/clover_folktale/taobao-scraper.md
- **Developed by:** [Silkline](https://apify.com/clover_folktale) (community)
- **Categories:** E-commerce, Lead generation
- **Stats:** 16 total users, 6 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $8.00 / 1,000 results

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 Scraper searches Taobao (淘宝) and Tmall (天猫) products by keyword and returns clean, flat JSON records. For every product you get the price and discount price, the sales count, the shop name, ID and ratings, the seller level, where the item ships from, stock and images. It is built for sellers, sourcing teams, analysts and developers who need China e-commerce product data without a Taobao account. No Taobao account, API keys, proxies or cookies are needed.

Pricing is pay-per-event: **$0.008 per product**, plus a $0.03 start fee per run. 100 products from one keyword cost about $0.83.

### What is Taobao?

Taobao (淘宝) is a large Chinese online marketplace run by Alibaba, where many independent shops sell to consumers. Tmall (天猫) is its sister platform for brand and official stores, and Tmall products also appear in Taobao search results. This Actor works on the Taobao search results page, so it covers both regular Taobao shops and Tmall stores.

### What data can you get?

Each dataset item is one product (`type` is `product`). The most useful fields come first.

#### Price and sales

| Field | Description |
|---|---|
| `price` | List price in Chinese yuan (CNY), as a number |
| `discountPrice` | Price in CNY after the shop's current promotion; equals `price` when there is none |
| `discountType` | Name of the current promotion, for example 特价秒杀; `null` when there is no promotion |
| `salesText` | Buyer count as Taobao shows it, for example `1万+` |
| `salesCount` | Lower bound of `salesText` as a number (`1万+` becomes 10000) |
| `commentCount` | Review count; usually empty in search results |
| `stock` | Stock count shown on the listing |

#### Shop

| Field | Description |
|---|---|
| `shopName` | Shop name |
| `shopId` | Shop ID |
| `isTmall` | `true` when the shop is a Tmall store |
| `sellerLevel` | Seller level shown by Taobao |
| `sellerPositiveRate` | Positive-review rate of the seller, in percent |
| `descriptionRating` | Shop rating for item as described, out of 5 |
| `serviceRating` | Shop rating for service, out of 5 |
| `shippingRating` | Shop rating for shipping, out of 5 |
| `sellerLocation` | Seller's location; empty for many shops |

#### Product

| Field | Description |
|---|---|
| `itemId` | Taobao item ID |
| `url` | Link to the item page on taobao.com |
| `title` | Item title (Chinese) |
| `titleEn` | English title; usually empty |
| `subtitle` | Selling-point line under the title; empty for many items |
| `spuId` | Standard product unit ID that groups the same product across shops |
| `imageUrl` | Main image URL |
| `imageUrls` | Further image URLs |
| `searchKeyword` | The search keyword this item was found with |
| `type` | Record type: `product` |

#### Delivery

| Field | Description |
|---|---|
| `itemLocation` | Where the item ships from (province and city) |

The numbers are ready to use: prices are numbers in CNY, the sales count comes both as text as Taobao shows it and as a number, and shop ratings are plain numbers out of 5.

### How to use Taobao Scraper

1. Open the Actor on Apify and click **Try for free** (or **Start**).
2. Enter one or more search keywords, in Chinese or English.
3. Optionally choose a sort order, turn on **Tmall only**, and set a minimum and maximum price.
4. Set **Max results** to the total number of products you want for the run.
5. Click **Start** and wait for the run to finish.
6. Open the **Products** view in the dataset and export the data as JSON, CSV or Excel, or fetch it through the API.

The Actor also runs with an empty input: `{}` searches 手机壳 (phone cases), which is a quick way to see the output format.

### Input

| Field | Type | Required | What it does | Default |
|---|---|---|---|---|
| `keywords` | array of strings | Optional | Search keywords, Chinese or English (for example 手机壳 or phone case). They are searched one after the other, and results are collected keyword by keyword until `maxResults` is reached. A later keyword is only searched if the earlier ones did not already fill `maxResults`. | Falls back to 手机壳 when empty |
| `sort` | string | Optional | `sales` (best selling), `priceHighToLow` (price, high to low) or `general` (Taobao's general ranking). Price low to high is not offered. | `sales` |
| `tmallOnly` | boolean | Optional | Only products from Tmall stores. | `false` |
| `minPrice` | number | Optional | Only products priced at least this many yuan (inclusive). Minimum 0. | none |
| `maxPrice` | number | Optional | Only products priced at most this many yuan (inclusive). Minimum 0. | none |
| `maxResults` | integer | Optional | Maximum number of products to return in total for this run, from 1 to 5000. A single keyword returns at most about 1000 products, so higher totals need several keywords. The run stops as soon as it is reached. You are charged per product returned. | 20 |

#### Example: best-selling products for one keyword

```json
{
  "keywords": ["手机壳"],
  "sort": "sales",
  "maxResults": 100
}
```

#### Example: Tmall stores only, within a price range

```json
{
  "keywords": ["蓝牙耳机"],
  "sort": "sales",
  "tmallOnly": true,
  "minPrice": 20,
  "maxPrice": 200,
  "maxResults": 100
}
```

#### Example: English keyword, most expensive first

```json
{
  "keywords": ["phone case"],
  "sort": "priceHighToLow",
  "maxResults": 50
}
```

When you give several keywords, they are searched in order. The run only moves on to the next keyword when the earlier ones did not fill `maxResults`. With a small `maxResults`, the first keyword often fills it, and the later keywords are never searched.

### Output example

One product record. Values are illustrative.

```json
{
  "type": "product",
  "itemId": "123456789012",
  "url": "https://item.taobao.com/item.htm?id=123456789012",
  "searchKeyword": "手机壳",
  "title": "透明磁吸手机壳 适用iPhone 防摔全包超薄保护套",
  "titleEn": null,
  "subtitle": "镜头全包 不易发黄",
  "price": 59.0,
  "discountPrice": 49.0,
  "discountType": "特价秒杀",
  "salesText": "1万+",
  "salesCount": 10000,
  "commentCount": null,
  "isTmall": true,
  "shopId": "1000000001",
  "shopName": "示例数码旗舰店",
  "sellerLevel": 19,
  "sellerPositiveRate": 100.0,
  "descriptionRating": 4.84,
  "serviceRating": 4.88,
  "shippingRating": 4.9,
  "itemLocation": "广东 东莞",
  "sellerLocation": "广东 深圳",
  "stock": 25000,
  "imageUrl": "https://img.alicdn.com/imgextra/i1/1000000001/example-main.jpg",
  "imageUrls": ["https://img.alicdn.com/imgextra/i1/1000000001/example-2.jpg"],
  "spuId": "8000000001"
}
```

### How much does it cost?

The Actor uses pay-per-event pricing. These are the charge events:

| Event | Price (USD) | When it is charged |
|---|---|---|
| `run-start` | $0.03 | Once per run, charged when the first request to the data source succeeds, even if that request returns nothing. It is not charged when the data source fails from the start, or when your spending limit cannot cover it. Each further keyword the run actually reaches pays one more start fee. That fee is charged before the keyword's first request and is kept even if that keyword then fails or returns nothing. A later keyword is only reached when the earlier ones did not fill `maxResults`. |
| `result` | $0.008 | For each product returned. |

Worked examples:

- 100 products from one keyword cost $0.03 + 100 × $0.008 = **$0.83**.
- 100 products from two keywords, when the first keyword returns fewer than 100 and the run moves on to the second, cost 2 × $0.03 + 100 × $0.008 = **$0.86**. If the first keyword already returns 100 products, the second keyword is not searched and the run costs $0.83.

You never pay for more than `maxResults` items, and you are never charged for items that were not delivered. The run stops by itself if your spending limit is reached.

On the free Apify plan, a run returns at most 10 results in total; any paid Apify plan removes the limit. On the free Apify plan each account can run this Actor up to 3 times per 24 hours and 10 times per 7 days, within a small lifetime free allowance shared across all our Actors, and all free accounts share a daily free budget. When any of these limits is reached, the run stops before fetching anything and nothing is charged.

### Use cases

- **Price monitoring and competitor research**: see how a product category is priced, which promotions run (`discountType`, `discountPrice`) and who sells the most (`salesCount`).
- **Sourcing and product selection**: find best-selling items per keyword, with shop quality at a glance through `descriptionRating`, `serviceRating`, `shippingRating` and `sellerPositiveRate`.
- **Market research for cross-border sellers**: see what sells on Taobao and Tmall before you list or source it.
- **Brand and Tmall store tracking**: use `tmallOnly` and `isTmall` to compare official Tmall stores with regular Taobao shops.
- **Regional supply analysis**: group products by `itemLocation` to see where items in a category ship from.
- **AI and data projects**: clean product records for catalogs, price models and recommendations.

### Integrations and API

You can start runs from your own code through the Apify API, schedule them on the Apify platform (for example a daily price check), and send results to other tools with Apify integrations and webhooks. Results are stored in a dataset you can download as JSON, CSV or Excel.

Python example using the `apify-client` package:

```python
from apify_client import ApifyClient

client = ApifyClient("<YOUR_APIFY_TOKEN>")
run = client.actor("clover_folktale/taobao-scraper").call(run_input={
    "keywords": ["蓝牙耳机"],
    "sort": "sales",
    "tmallOnly": True,
    "minPrice": 20,
    "maxPrice": 200,
    "maxResults": 100,
})
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)
```

### Tips and limits

- **Reliability.** The Actor retries transient errors on its own and stops cleanly instead of failing half-way. It never charges for items it did not deliver.
- **Speed.** A page holds 10 products, so large runs make many requests; expect roughly 2-5 seconds per page. Different pages of one search do not overlap.
- **Run size.** `maxResults` is the total for the whole run (1 to 5000, default 20). A single keyword returns at most about 1000 products (often fewer, when the search runs out of pages), so to get more you need several keywords. With several keywords, results are collected keyword by keyword until the total is reached, and later keywords are not searched once the total is filled.
- **Sales counts.** `salesCount` is the lower bound of the sales text: `1万+` becomes 10000, `1000+` becomes 1000. Taobao only gives rounded buyer counts in search results.
- **Price filters.** `minPrice` and `maxPrice` are in yuan and both inclusive. A narrow price range can return no products at all; widen the range if that happens.
- **Nothing found.** A search that finds nothing is skipped. If too many keywords return nothing, the run stops to protect your budget.
- **Currency.** Prices are in Chinese yuan (CNY) and are what Taobao shows at the time of the run.
- **Sorting.** Price low to high is not offered; use `priceHighToLow`, `sales` or `general`.
- **Empty fields.** `commentCount` and `titleEn` (the English title) are empty in search results. `subtitle` and `sellerLocation` are empty for many products. `discountType` is `null` when the product has no promotion.
- **Free plan.** On the free Apify plan a run returns at most 10 results in total; any paid Apify plan removes the limit.
- **Privacy.** Only public listing data is returned: what anyone sees on a Taobao search page, such as the shop name, its ratings and the item's ship-from location. No buyer data, no private shop data.

### FAQ

#### Do I need a Taobao account, cookies or an API key?

No. No Taobao account, API keys, proxies or cookies are needed. You only need an Apify account to run the Actor.

#### Is this the official Taobao API?

No. This Actor is not affiliated with Taobao or Tmall. It is an independent tool that collects public search-result data and returns it as structured JSON, so you can use it as an alternative to building your own Taobao product search integration.

#### Is it legal to scrape Taobao?

The Actor only returns public listing data that anyone can see on a Taobao search page. It does not return buyer data, private shop data, phone numbers or messages. You are responsible for how you use the data and for following the laws and rules that apply to you.

#### How fresh is the data?

The data is collected live during each run. Prices, sales counts and stock are what Taobao shows at the time of the run.

#### Why are some fields empty?

Taobao search results do not include every field for every product. `commentCount` and `titleEn` are empty in search results, `subtitle` and `sellerLocation` are empty for many products, and `discountType` is `null` when there is no promotion.

#### Can I get reviews, SKUs or full product details?

No. This Actor works on keyword search results only. It returns the fields listed in the data table above.

#### How many results can I get?

You can set `maxResults` up to 5000 per run, but a single keyword returns at most about 1000 products, often fewer. To get more, add more keywords. On the free Apify plan a run returns at most 10 results in total; any paid plan removes the limit.

#### Can I schedule runs and export the data?

Yes. You can schedule runs on Apify, start them through the API, and export the dataset as JSON, CSV or Excel.

#### Something is missing. How do I ask for it?

Missing a field or a filter? Open an issue from the Actor page and it will be looked at.

### More tools from the same developer

- [1688 阿里巴巴 Scraper - Wholesale Prices & Suppliers](https://apify.com/clover_folktale/1688-scraper)
- [Douyin Shop 抖音商城 Scraper - Products, Sales, Commission](https://apify.com/clover_folktale/douyin-shop-scraper)
- [TikTok Shop Scraper - Products, SKUs, Reviews & Reviewer IDs](https://apify.com/clover_folktale/tiktok-shop-scraper)
- [Amazon Scraper - Products, Prices, Ratings & Best Sellers](https://apify.com/clover_folktale/amazon-scraper)
- [Xiaohongshu 小红书 RedNote Scraper - Notes, Comments & User IP](https://apify.com/clover_folktale/xiaohongshu-scraper)
- [WeChat Index 微信指数 Scraper - Keyword Trends & Popularity](https://apify.com/clover_folktale/wechat-index-scraper)

# Actor input Schema

## `keywords` (type: `array`):

Search keywords, Chinese or English (for example 手机壳 or phone case). Results are collected keyword by keyword until Max results is reached. Falls back to 手机壳 when empty.

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

Best-selling first, price high to low, or Taobao's general ranking.

## `tmallOnly` (type: `boolean`):

Only products from Tmall stores.

## `minPrice` (type: `number`):

Only products priced at least this many yuan.

## `maxPrice` (type: `number`):

Only products priced at most this many yuan.

## `maxResults` (type: `integer`):

Maximum number of products to return in total for this run. You are charged per product returned. On the free Apify plan a run returns at most 10 results in total; any paid Apify plan removes the limit.

## Actor input object example

```json
{
  "keywords": [
    "手机壳"
  ],
  "sort": "sales",
  "tmallOnly": false,
  "maxResults": 20
}
```

# Actor output Schema

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

All scraped items (JSON, CSV, Excel via the dataset API).

# 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 = {
    "keywords": [
        "手机壳"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("clover_folktale/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 = { "keywords": ["手机壳"] }

# Run the Actor and wait for it to finish
run = client.actor("clover_folktale/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 '{
  "keywords": [
    "手机壳"
  ]
}' |
apify call clover_folktale/taobao-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,clover_folktale/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/EIwBU8gdDHlmqN4Rl/builds/pkUbvlnpQbFwWusRA/openapi.json