# Taobao & Tmall Scraper — Products, Prices, Shops & Ratings (`tortuga/taobao-scraper`) Actor

Scrape Taobao and Tmall products by keyword, category, shop or item URL: CNY prices, discounts, shop names, seller ratings, ship-from location and review summary. No login.

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

## Pricing

from $2.00 / 1,000 product scrapeds

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

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 — Products, Prices, Shops & Ratings

Scrape **Taobao (淘宝)** and **Tmall (天猫)** products by keyword, category, shop or item URL. Get CNY prices and price labels, shop names and IDs, seller service scores, ship-from location, Tmall vs. Taobao, rating split, review counts and review highlights. No login, no cookies, no browser: plain HTTP against the catalogue pages Taobao publishes for search engines and overseas shoppers.

Use it for price research and monitoring, finding best sellers in a niche, comparing shops, sourcing for cross-border resale, or feeding a product database.

### What data does Taobao & Tmall Scraper extract?

| Field | Example | Where |
|---|---|---|
| `itemId`, `url` | `765833709683`, item.taobao.com / detail.tmall.com link | all |
| `title` | `华强北Pro3代蓝牙耳机降噪无线2026新款...` (Simplified Chinese, as the seller wrote it) | all |
| `price`, `currency` | `388`, `CNY` (current selling price) | all |
| `discountLabel` | `超级立减活动价` (Taobao's price label: campaign price, flash sale...) | listings |
| `image`, `images` | main image URL | all |
| `shopId`, `shopName` | `467290190`, `深圳华强北正品直销总店` | all |
| `categoryId`, `rootCategoryId` | `50005050`, `50011972` | all |
| `descriptionScore` | `4.75` (shop's "item as described" score, 1-5) | all |
| `freeShipping`, `sellingPoints`, `reviewTags` | `false`, `["华强北原装正品"]`, `[{"tag":"价格很低","count":850}]` | listings |
| `position`, `searchSlice`, `searchTerm`, `sourceType` | rank on the page, deep-scan slice (`price 100-200 CNY`), source | listings |
| `platform` | `tmall` or `taobao` | details |
| `originalPrice`, `hasPriceRange` | `66`, `false` | details |
| `location` | `广东深圳` (ships from) | details |
| `categoryPath` | `["阿里B2C商城","手机及配件","手机配件","保护套/硅胶套"]` | details |
| `sellerId`, `sellerType` | `1956033748`, `B` (business / Tmall) or `C` (individual) | details |
| `shopOpenedAt`, `shopAgeYears`, `sellerCreditLevel`, `shopItemCount` | `2014-01-08`, `12`, `18`, `5640` | details |
| `shopScores`, `shopScoresVsIndustry` | `{"description":4.7,"service":4.8,"delivery":4.8}`, `{"service":"same",...}` | details (scores also on shop listings) |
| `positiveRate`, `neutralRate`, `negativeRate`, `positiveReviewCount` | `100`, `0`, `0`, `200` (Taobao items; Tmall does not publish the split) | details |
| `reviewCount`, `reviewHighlights` | `300`, `[{"tag":"外形外观好看","count":35}]` | details |
| `latestReview` | `{"rating":5,"text":"...","date":"2026-09-18","variant":"颜色分类:..."}` | details |

"Details" fields come from the item page: turn on **Include item details**, or pass item URLs / IDs (always with details).

### How to use Taobao & Tmall Scraper

1. Enter **Search terms** (e.g. `手机壳`), and/or **Start URLs** (item, shop, category or search pages), **Item IDs** or **Shop IDs**.
2. Optionally pick **Sort by**, a **Min / Max price** in yuan, and turn on **Include item details**.
3. Set **Max items** and click **Start**. Download the results as JSON, CSV or Excel, or read them via the API.

### Input example

```json
{
  "searchTerms": ["蓝牙耳机"],
  "shopIds": ["72104903"],
  "startUrls": [{ "url": "https://detail.tmall.com/item.htm?id=1081364414020" }],
  "sortBy": "sales",
  "deepScan": true,
  "includeDetails": false,
  "maxItems": 150
}
```

### Output example

A search result (listing fields; detail fields stay `null` without **Include item details**):

```json
{
  "itemId": "765833709683",
  "title": "华强北Pro3代蓝牙耳机降噪无线2026新款5洛达顶配2高音质超长待机",
  "url": "https://item.taobao.com/item.htm?id=765833709683",
  "price": 388,
  "currency": "CNY",
  "discountLabel": "超级立减活动价",
  "image": "https://img.alicdn.com/imgextra/i3/2523443838/O1CN01QULkBg1eDrFVYcid7_!!2523443838.jpg",
  "shopId": "467290190",
  "shopName": "深圳华强北正品直销总店",
  "categoryId": "50005050",
  "descriptionScore": 4.75,
  "freeShipping": false,
  "sellingPoints": ["华强北原装正品", "外观1"],
  "position": 1,
  "searchSlice": null,
  "sourceType": "search",
  "searchTerm": "蓝牙耳机"
}
```

An item URL (with item page details):

```json
{
  "itemId": "1081364414020",
  "title": "优思顿适用苹果18p...",
  "titleTruncated": true,
  "url": "https://detail.tmall.com/item.htm?id=1081364414020",
  "platform": "tmall",
  "price": 66,
  "originalPrice": 66,
  "location": "广东深圳",
  "categoryPath": ["阿里B2C商城", "手机及配件", "手机配件", "保护套/硅胶套"],
  "shopId": "108337685",
  "shopName": "优思顿数码旗舰店",
  "sellerType": "B",
  "shopOpenedAt": "2014-01-08",
  "shopAgeYears": 12,
  "shopItemCount": 5640,
  "shopScores": { "delivery": 4.8, "service": 4.8, "description": 4.7 },
  "shopScoresVsIndustry": { "delivery": "same", "service": "same", "description": "lower" },
  "reviewCount": 300,
  "reviewHighlights": [{ "tag": "外形外观好看", "count": 35 }, { "tag": "质量超好", "count": 20 }],
  "latestReview": { "rating": 5, "text": "...", "date": "2026-09-18", "variant": "颜色分类:..." }
}
```

### How many results do I get per search?

Taobao shows signed-out visitors **one page per listing**: the 20 best sellers of a keyword or category, and 60 products of a shop. Deeper pages need a Taobao login, which this Actor does not use. With **Deep scan** on (default), the Actor also reads the keyword's best sellers in 9 price bands (starting with the bands closest to the typical price, or cheapest / dearest first when you sort by price), which gives up to ~200 unique products per keyword, and a shop in two more sort orders (price low-high and high-low), up to 180 products. Category pages always return their 20 best sellers. With several searches, **Max items** is shared equally between them.

### How much does it cost?

You pay per result: **$0.002 per product** from a listing, plus **$0.0025 per item page** when details are included (item URLs / IDs are always charged as a product with details, $0.0045). 1,000 products from searches cost $2; with details $4.50. Proxy and compute usage is billed to your Apify account on top: about $0.02 per 1,000 listing products (residential traffic, ~40 KB per 20-product page) and roughly $0.1-0.5 per 1,000 item pages.

### Does it work with English keywords?

Taobao does not translate keywords. An English keyword matches products whose titles contain the English words (e.g. `phone case` found 15,000+ listings with "case" in the title), so Chinese keywords reach far more of the market. Titles are returned in Simplified Chinese as the sellers wrote them.

### Monitor changes on a schedule

Turn on **Only new or changed items** and the Actor remembers what earlier runs of the same input returned: each run outputs only products that are new in the watched results or whose `price` (or, with details, `originalPrice`) changed. Unchanged products are dropped on the listing, before any item page is opened, so they cost nothing; item URLs and IDs are compared after their page is read and are not charged when unchanged. **Max items** becomes the window checked on every run, e.g. the first 60 best sellers of a keyword. Save the input as a task and add a Schedule to it in Apify Console (for example daily). Every output product carries `changeType` (`new` or `changed`); changed ones carry `previousValues`, e.g. `{"price": 54.9}`. Use **Monitoring key** to keep several schedules on the same search separate.

### Does it work without login?

Yes. item.taobao.com, detail.tmall.com and s.taobao.com ask signed-out visitors to log in, so the Actor reads the server-rendered catalogue Taobao publishes for search engines and overseas visitors (`www.taobao.com/list/...`, and `sg.world.taobao.com` for sorted, price-filtered and deep-scan searches). Those pages are shown only outside mainland China, so the Actor uses Apify's residential proxy in the US by default and opens every page as a new visitor on a new IP. It does not solve captchas and never logs in. What a signed-out visitor cannot see is not available: SKU variants and stock, specification tables, all gallery images, description images, monthly sales counts and full review lists. Item pages show a shortened title; products from listings keep their full title.

### Integrations and API

Use the results in Make, Zapier, n8n or Google Sheets, or call the Actor from Python or JavaScript with the Apify client. The **API** tab has ready-made snippets.

### Is it legal to scrape Taobao?

The Actor collects only data Taobao shows publicly to signed-out visitors: product listings, prices, shop names and published shop ratings, and review summaries. It does not log in, does not reveal hidden values and does not export reviewer names (Taobao masks them). You are responsible for how you use the data and for complying with Taobao's terms and applicable law.

### Support

Found a bug or need a field? Open an issue in the **Issues** tab.

# Actor input Schema

## `searchTerms` (type: `array`):

Keywords to search on Taobao and Tmall, one per line. Chinese keywords give the best results (e.g. 手机壳, 蓝牙耳机). English keywords are not translated: they match listings whose titles contain the English words. Taobao shows visitors the first 20 best sellers of a search; turn on Deep scan to collect more.

## `startUrls` (type: `array`):

Taobao / Tmall URLs: item pages (item.taobao.com/item.htm?id=..., detail.tmall.com/item.htm?id=..., world.taobao.com/item/<id>.htm), shop pages (shop<id>.taobao.com, world.taobao.com/dianpu/<id>.htm), category pages (world.taobao.com/category/<id>.htm, 20 best sellers) and search pages (s.taobao.com/search?q=..., world.taobao.com/product/<keyword>.htm). Item URLs always include the item page details.

## `itemIds` (type: `array`):

Taobao / Tmall item IDs (the id=... number of an item URL), one per line. Each is scraped with item page details: a watchlist for price monitoring.

## `shopIds` (type: `array`):

Taobao / Tmall shop IDs (every result has shopId; the number in shop<id>.taobao.com), one per line. Returns the shop's listed products (60 per sort order) with the shop's ratings.

## `sortBy` (type: `string`):

Order of keyword search results. 'sales' = best sellers first (Taobao's default). Price orders use Taobao's price sort for the first page (if Taobao has no sorted page for a keyword, best sellers in your price range are returned instead) and read the deep-scan price bands cheapest or dearest first. Price orders also apply to shops; category pages are always best sellers.

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

Only items priced at or above this many yuan. Sent to Taobao's search and checked again on every result (results outside the range are dropped, not charged).

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

Only items priced at or below this many yuan. Sent to Taobao's search and checked again on every result.

## `deepScan` (type: `boolean`):

Taobao shows visitors one page per listing (20 results for a keyword, 60 for a shop). Deep scan also reads the keyword's best sellers in 9 price bands (up to ~200 unique items) and a shop in two more sort orders (up to 180). Turn off to read just the first page.

## `includeDetails` (type: `boolean`):

Open each item page for Tmall/Taobao platform, price before discount, ship-from location, category path, seller profile (shop age, credit level, item count, service scores vs. industry), rating split, review count and highlights, and the latest review. Charged as an extra 'detail' event per item.

## `maxItems` (type: `integer`):

Stop after this many items in total. With several searches and deep scan, each search gets an equal share. You pay per item saved, so this caps the cost.

## `onlyNewOrChanged` (type: `boolean`):

Remember what earlier runs of this search returned and output only new items or items whose price/status changed. Use with a Schedule; unchanged items are not charged.

## `monitoringKey` (type: `string`):

Name for this watch, so several schedules on the same search stay separate; defaults to a key derived from the search input

## `proxyConfiguration` (type: `object`):

Taobao shows its public catalogue only to visitors outside mainland China (Chinese IPs get a login page), so the default is Apify RESIDENTIAL proxy in the US; country CN is replaced automatically. Datacenter proxy is cheaper but gets captchas on sorted, price-filtered and deep-scan searches. Residential traffic is billed to your Apify account: about 20 KB per 20-item page and 10-60 KB per item page.

## Actor input object example

```json
{
  "searchTerms": [
    "手机壳"
  ],
  "sortBy": "sales",
  "deepScan": true,
  "includeDetails": false,
  "maxItems": 100,
  "onlyNewOrChanged": false,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  }
}
```

# Actor output Schema

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

No description

# 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 = {
    "searchTerms": [
        "手机壳"
    ],
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ],
        "apifyProxyCountry": "US"
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("tortuga/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 = {
    "searchTerms": ["手机壳"],
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
        "apifyProxyCountry": "US",
    },
}

# Run the Actor and wait for it to finish
run = client.actor("tortuga/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 '{
  "searchTerms": [
    "手机壳"
  ],
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  }
}' |
apify call tortuga/taobao-scraper --silent --output-dataset

```

## MCP server setup

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