# Taobao & Tmall Scraper: Product Data in English, USD Prices (`forgedata/taobao-tmall-scraper`) Actor

Scrape Taobao (淘宝) and Tmall (天猫) by keyword, category, shop or item id. No login, no browser. Prices in CNY plus USD, EUR, GBP and 9 more currencies, seller DSR scores, ships-from city, review tags. English columns, pay per product.

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

## Pricing

from $2.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 Product Scraper: prices, sellers, reviews, no login

Extract products from **Taobao (淘宝) and Tmall (天猫)** by keyword, category, shop or item id, and get clean JSON, CSV or Excel: title, promo and original price in CNY converted to USD, EUR, GBP, SGD, MYR, AUD, JPY, KRW, THB, CAD, HKD and TWD, shop, category, seller type and credit level, the seller's three DSR scores, ships-from city, review tag counts and a sample review.

No Taobao account, no cookies, no browser. Datacenter proxies are enough. English field names throughout, so you don't need to read Chinese to use the columns.

> This Actor is an independent tool and is not affiliated with, endorsed by or sponsored by Alibaba Group. Taobao and Tmall are referenced only to describe the public website it reads.

### What it does

| Give it | Get |
|---|---|
| **Keywords** (手机壳, 奶粉, iphone case) | The products Taobao lists for the keyword, plus the products of related keywords buyers actually search (deep scan, see below) |
| **Category ids** (1512 = phones) | The category's listed products, plus related keyword pages |
| **Shop ids** (539056969) | The shop's catalog, up to 60 products, each with the shop's seller scores |
| **Item ids or product URLs** | One row per item with live price, seller details and a sample review |
| **Open each product page** (option) | Adds seller type, credit level, DSR scores, location, category path, review tags, payment methods and original vs promotion price to every row |

Prices are the real prices shown to shoppers, not the masked ones on the product page.

### Why this scraper

- **It reads the pages Taobao publishes for search engines.** Taobao's consumer pages sit behind a login wall and Alibaba's bot defenses; its SEO catalog on `world.taobao.com` is server-rendered, carries the product data as JSON, and is explicitly allowed for crawlers in Taobao's own robots.txt. Reading that surface is why runs are fast and dependable.
- **Retries rotate IPs automatically.** Taobao throttles single IPs hard. Every throttled response is retried on a fresh IP without any configuration. On our test runs, 181 of 181 requests succeeded.
- **Deep scan finds more than the 20 products per page.** Taobao's crawlable catalog ignores paging, sorting and filters: one keyword page is one page of 20. Instead of pretending otherwise, deep scan asks Taobao's own search-box autocomplete for the related keywords buyers use (奶粉 → 奶粉3段, 奶粉试用装 ...), reads each of those keyword pages too, follows the breadcrumb category, and dedupes. On our run of 奶粉 that turned 20 products into 60 in under a minute; 手机壳 reached 108 with 15 extra pages. Every row says which keyword it was found through (`foundVia`).
- **One row per product, with English column names.** Chinese text values are kept as Taobao shows them; everything else is typed and named for a spreadsheet.
- **Cheap to run.** Pay per product, no platform usage charged on top. A 150-product run with every product page opened cost about two cents of platform usage on our tests.

### Pricing

Pay per event. You are not charged for platform usage.

| Event | Price |
|---|---|
| Product returned | $2.50 per 1,000 |
| Product page opened (only with *Open each product page* on) | +$2.50 per 1,000 |

So a product list costs $2.50 per 1,000 rows, and a fully detailed list $5 per 1,000 rows.

### Input

```json
{
    "keywords": ["奶粉", "iphone case"],
    "shopIds": ["539056969"],
    "itemIds": ["1083028793486"],
    "maxItemsPerQuery": 100,
    "deepScan": true,
    "includeDetails": true
}
```

| Field | Type | Default | What it does |
|---|---|---|---|
| `keywords` | array of strings | | Search words, Chinese or English. Chinese keywords give the widest results and the best deep scan. |
| `startUrls` | array of `{url}` | | `item.taobao.com/item.htm?id=...`, `detail.tmall.com/item.htm?id=...`, `world.taobao.com/item/...`, `world.taobao.com/product/<keyword>.htm`, `world.taobao.com/category/<id>.htm`, `world.taobao.com/dianpu/<shopId>.htm`, `s.taobao.com/search?q=...` |
| `itemIds` | array of strings | | Item ids, one row each |
| `categoryIds` | array of strings | | Taobao category ids (`categoryId` column of results, or `world.taobao.com/category/<id>.htm`) |
| `shopIds` | array of strings | | Shop ids (`shopId` column of results, or `world.taobao.com/dianpu/<id>.htm`) |
| `maxItemsPerQuery` | integer | 100 | Unique products per keyword, category or shop |
| `deepScan` | boolean | true | Read related keyword pages and the breadcrumb category to get past 20 products |
| `maxFacetPages` | integer | 40 | Upper bound on extra pages per query |
| `includeDetails` | boolean | false | Open each product page for seller and review fields |
| `region` | select | Global | Overseas storefront to read (Singapore, Malaysia, Japan ...). Prices stay in CNY with HKD/TWD alongside. |
| `maxConcurrency` | integer | 10 | Parallel requests |
| `proxyConfiguration` | proxy | Apify datacenter | Residential is not needed for this site |

### Output

One row per product. Listing fields come on every row; detail fields come when *Open each product page* is on or when you pass item ids.

**Identity:** `itemId`, `itemIdStr`, `url`, `taobaoUrl`, `title`

**Price:** `priceCny` (promo price), `originalPriceCny`, `priceHkd`, `priceTwd` (Taobao's own conversions), plus `priceUsd`, `priceEur`, `priceGbp`, `priceSgd`, `priceMyr`, `priceAud`, `priceJpy`, `priceKrw`, `priceThb`, `priceCad` (converted at the day's rate, fetched at run start), `priceLocal`, `priceCurrency`, `discountType`, `freeShipping`, `areaLimit`

**Shop and category:** `shopId`, `shopName`, `categoryId`, `rootCategoryId`, `descriptionMatchScore`, `reviewTags`

**Media:** `imageUrl`, `images`

**Context:** `queryType` (keyword / category / shop / item), `query`, `foundVia` (the related keyword or category page the product came from), `position`, `totalResultsForQuery` (how many products Taobao reports for the query), `scrapedAt`

**Shop mode adds:** `sellerId`, `shopDsrDelivery`, `shopDsrService`, `shopDsrDescription`

**Detail fields:** `detailStatus`, `platform` (taobao / tmall), `location` (ships from), `categoryPath`, `promotionPriceCny`, `hasRangePrice`, `priceNote`, `detailImages`, `seller` {`shopId`, `shopName`, `sellerId`, `sellerType` (business / individual), `creditLevel`, `itemCount`, `newItemCount`, `shopOpenedAt`, `shopIcon`, `dsrDelivery`, `dsrService`, `dsrDescription`}, `sampleReview` {`rating`, `text`, `date`, `sku`, `user`}, `hasMoreReviews`, `reviewCountText`, `reviewSummary` \[{`count`, `tag`}], `paymentMethods`, `sellableLanguages`

Example row (detail on):

```json
{
    "itemId": "1083028793486",
    "title": "【需當面激活丨12期免息】Apple/蘋果 iPhone 18 Pro Max 手機 2026新款 全新國行 官方正品全國聯保",
    "url": "https://world.taobao.com/item/UmhOMm04UFJRL2ZYY0FmdnIxdnp6Zz09.htm",
    "taobaoUrl": "https://item.taobao.com/item.htm?id=1083028793486",
    "priceCny": 10999,
    "priceUsd": 1545.26,
    "priceEur": 1329.88,
    "priceHkd": 13075.61,
    "priceTwd": 53984.19,
    "discountType": "優惠價",
    "shopId": "539056969",
    "shopName": "Apple產品健康專營店",
    "categoryId": "1512",
    "platform": "tmall",
    "location": "江蘇南京",
    "seller": { "sellerType": "business", "creditLevel": 8, "itemCount": 54, "dsrDelivery": 4.9, "dsrService": 4.8, "dsrDescription": 4.9 },
    "sampleReview": { "rating": 5, "text": "發貨速度快，隔天就到了。而且國補後 很優惠。", "date": "2026.09.20 10:33" },
    "reviewSummary": [{ "count": 21, "tag": "物流速度很快" }, { "count": 22, "tag": "性價比高" }],
    "queryType": "keyword",
    "query": "iphone"
}
```

### Tmall only?

Want just Tmall's official brand stores? Turn on *Open each product page* and every row gets a `platform` field set to `tmall` or `taobao`. Filter on it in the dataset view, Excel or your code. You can also pass a Tmall flagship store's `shopId` to get that store's catalog directly.

### Honest limits

- **20 products per listing page.** Taobao's crawlable catalog ignores page, sort and filter parameters. Deep scan works around this with related keyword pages; the number of unique products per keyword depends on how many related keywords Taobao suggests (Chinese keywords get the most).
- **Titles on item-id rows can be shortened** (Taobao truncates the title on the detail page). Rows found through a keyword, category or shop carry the full title.
- **One sample review per product** and aggregated review tag counts. Full review pagination and the full image gallery are only behind Taobao's browser-only API.
- **Tmall listings don't publish the buyer rating breakdown**, so `reviewSummary` is empty on some Tmall rows. You still get the seller DSR scores and a sample review.
- **English keywords** work when Taobao has a page for them (iphone case does); their autocomplete suggestions often don't, so deep scan adds less. Use Chinese keywords for breadth.

### Use with AI agents (MCP)

This Actor works as a tool through the Apify MCP server. Ask Claude, ChatGPT or your own agent to pull Taobao prices, seller quality or a shop's catalog and it can call this scraper directly. It uses pay-per-event pricing with limited permissions, so it also qualifies for agentic payments (no Apify account needed).

### Use via API

```python
from apify_client import ApifyClient

client = ApifyClient("<YOUR_API_TOKEN>")
run = client.actor("<ACTOR_ID>").call(run_input={
    "keywords": ["奶粉"],
    "maxItemsPerQuery": 200,
    "includeDetails": True,
})
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item["title"], item["priceCny"], item["shopName"])
```

### Legal

This scraper reads publicly available product listings that Taobao publishes for search engines, in line with Taobao's robots.txt. It does not log in, bypass CAPTCHAs or access private data. You are responsible for how you use the data; respect Taobao's terms and applicable law, and don't collect personal data.

# Actor input Schema

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

Search words, one per line. Chinese keywords (手機殼, 奶粉) return the most results; English works too (iphone case).

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

Product pages (item.taobao.com, detail.tmall.com, world.taobao.com/item/...), keyword pages (world.taobao.com/product/...), category pages (world.taobao.com/category/...), shop pages (world.taobao.com/dianpu/...) or s.taobao.com search URLs.

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

Taobao / Tmall item ids, e.g. 1083028793486. One row per item with live price and seller details.

## `categoryIds` (type: `array`):

Taobao category ids, e.g. 1512 (phones). Found in the categoryId column of results or in world.taobao.com/category/<id>.htm links.

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

Taobao / Tmall shop ids, e.g. 539056969. Returns the shop's catalog (up to 60 products per shop) with the shop's seller scores.

## `maxItemsPerQuery` (type: `integer`):

Stop collecting for a query after this many unique products.

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

Taobao's crawlable catalog serves 20 products per keyword page. Deep scan asks Taobao's own search autocomplete for the related keywords buyers use (手机壳 -> 手机壳磁吸, 手机壳带支架 ...), reads each of those pages too, and dedupes. Works best with Chinese keywords.

## `maxFacetPages` (type: `integer`):

Upper bound on extra keyword and category pages fetched by deep scan for one query (each adds up to 20 products).

## `followRelatedKeywords` (type: `boolean`):

Also fetch the related-search keywords Taobao links from each keyword page (counted toward the same query's limit).

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

Fetch every product's page for seller type and credit level, the three seller DSR scores, ships-from location, category path, a sample review and review tag counts, payment methods and original vs promotion price. Slower and charged per product page.

## `region` (type: `string`):

Taobao overseas storefront to read. Global (Traditional Chinese, CNY with HKD/TWD) by default.

## `maxConcurrency` (type: `integer`):

Parallel requests. Lower it if you see many retries.

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

Apify datacenter proxies work well for this site and are the default. Choose residential only if you see persistent blocks.

## Actor input object example

```json
{
  "keywords": [
    "iphone case"
  ],
  "maxItemsPerQuery": 100,
  "deepScan": true,
  "maxFacetPages": 40,
  "followRelatedKeywords": false,
  "includeDetails": false,
  "region": "",
  "maxConcurrency": 10,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# 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 = {
    "keywords": [
        "iphone case"
    ],
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("forgedata/taobao-tmall-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": ["iphone case"],
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("forgedata/taobao-tmall-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": [
    "iphone case"
  ],
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call forgedata/taobao-tmall-scraper --silent --output-dataset

```

## MCP server setup

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