# Taobao & Tmall Product Scraper: Search, Category, Shop (`kyungminlee/taobao-catalog-scraper`) Actor

Scrape Taobao and Tmall products by keyword, category or shop from Taobao's public catalogue - no login, no browser. Splits each keyword across sort orders, price bands and brands to return hundreds of unique products, with clean CNY prices, USD conversion, shop scores and search/sales ranks.

- **URL**: https://apify.com/kyungminlee/taobao-catalog-scraper.md
- **Developed by:** [Kyungmin Lee](https://apify.com/kyungminlee) (community)
- **Categories:** E-commerce, Marketing, Lead generation
- **Stats:** 4 total users, 0 monthly users, 96.7% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 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

### What does Taobao Catalog Scraper do?

**Taobao Catalog Scraper** collects Taobao and Tmall products by **keyword, category or shop** and returns them as clean, structured data: title, CNY price (plus HKD, TWD and an optional conversion to USD or 28 other currencies), promotion label, shop name and score, category IDs, image, selling points, review tags, Taobao's search ranking position and direct product URLs.

It reads only Taobao's **public, crawler-facing catalogue at `www.taobao.com/list/`**, the server-rendered pages Taobao publishes for search engines. Its `robots.txt` explicitly allows every crawler there. There is **no login, no cookies, no browser and no slider solving**, so runs are fast and cheap.

This is an **unofficial** tool. It is not affiliated with, endorsed by or sponsored by Taobao, Tmall or Alibaba Group.

### Why use Taobao Catalog Scraper?

- **Product and market research**: see what sells for a keyword, at which prices, from which shops and brands.
- **Sourcing**: shortlist suppliers by price, shop score and promotion, then open the product in one click.
- **Price benchmarking**: numeric CNY prices plus a same-day USD/EUR/KRW conversion from the European Central Bank.
- **Rank tracking**: `searchRank` is the product's position (1-40) in Taobao's own ranking for the keyword. Schedule a daily run to watch positions move.
- **Shop monitoring**: list a competitor's catalogue with its service and delivery scores.

**More than 20 products per keyword.** A Taobao catalogue page shows only 20-40 products and has no "next page", so a single query can never return more. This Actor widens coverage step by step and stops as soon as you have enough products:

1. the keyword page and its 40-product top-rated page;
2. **brand refinements**: `<brand> <keyword>` for up to 30 brands that Taobao itself lists for the keyword (e.g. `罗技 机械键盘`);
3. **attribute refinements**: `<value> <keyword>` for attribute values Taobao lists (e.g. `青轴 机械键盘`);
4. **sort orders and automatic CNY price bands**, only where Taobao honours these parameters for your proxy's region (it ignores them for US IPs, which Apify Proxy uses by default; the Actor detects this after one request).

Every product is returned once (de-duplicated by item ID) and `foundBy` tells you which step found it. A typical keyword yields a few hundred to about 1,000 unique products. Any scraper of this public catalogue faces the same 20-40-per-page limit; this Actor is upfront about it.

### How to scrape Taobao products

1. Enter one or more **keywords**. Chinese works best (`机械键盘`, `蓝牙耳机`, `连衣裙`). Common English words such as `keyboard` or `iphone case` work too, but many English phrases have no catalogue page.
2. Optionally add **category IDs** or **shop IDs** (any `categoryId` / `shopId` from a previous run).
3. Set **Max products per query** and, if you like, a CNY **price range** and a currency to convert to.
4. Click **Start** and download the dataset as JSON, CSV or Excel, or fetch it via the API.

### Input

| Field | Default | Description |
|---|---|---|
| `keywords` | `["机械键盘"]` | Search keywords or `www.taobao.com/list/product/...` URLs |
| `categoryIds` | – | Category IDs or `/list/category/<id>.htm` URLs |
| `shopIds` | – | Shop IDs, `/list/dianpu/<id>.htm` or `shop<id>.taobao.com` URLs |
| `maxItemsPerQuery` | `100` | Unique products per keyword, category or shop |
| `refineByBrand` | `true` | Widen keyword coverage with `<brand> <keyword>` |
| `refineByAttribute` | `true` | Widen keyword coverage with `<attribute value> <keyword>` |
| `splitByPriceBands` | `true` | Sort orders and price bands where Taobao honours them (not on US IPs) |
| `minPrice` / `maxPrice` | – | CNY price filter (out-of-range products are dropped, not charged) |
| `convertPricesTo` | `USD` | Currency for `priceConverted` (ECB rate) or `NONE` |
| `deduplicateAcrossQueries` | `true` | Return a product only once per run |
| `proxyConfiguration` | Apify Proxy | Datacenter proxy; the IP rotates every 30 requests and after any block |

```json
{
  "keywords": ["机械键盘", "蓝牙耳机"],
  "maxItemsPerQuery": 500,
  "minPrice": 50,
  "convertPricesTo": "USD"
}
```

### Output

```json
{
  "itemId": "991372610509",
  "title": "机械手感有线静音电脑键盘鼠标套装笔记本游戏电竞外设三件套办公",
  "titleEn": null,
  "price": 34.8,
  "currency": "CNY",
  "priceConverted": 5.19,
  "convertedCurrency": "USD",
  "priceHkd": 41.16,
  "priceTwd": 166.56,
  "promotionLabel": "超级立减活动价",
  "freeShipping": false,
  "areaLimited": false,
  "shopId": "465965982",
  "shopName": "天天特卖工厂",
  "shopUrl": "https://www.taobao.com/list/dianpu/465965982.htm",
  "descriptionMatchScore": 4.75,
  "shopServiceScore": null,
  "shopDeliveryScore": null,
  "categoryId": "110210",
  "rootCategoryId": "11",
  "image": "https://img.alicdn.com/imgextra/i3/3937219703/O1CN01OXYoId2LY28CBaSC1_!!3937219703-2-C2M.png",
  "sellingPoints": [],
  "reviewTags": [],
  "url": "https://www.taobao.com/list/item/991372610509.htm",
  "taobaoUrl": "https://item.taobao.com/item.htm?id=991372610509",
  "query": "机械键盘",
  "queryType": "keyword",
  "queryTotalResults": 18814,
  "searchRank": 1,
  "foundBy": "default",
  "scrapedAt": "2026-10-07T00:52:07Z"
}
```

A run summary is saved as `SUMMARY` in the run's key-value store at no extra cost. It holds requests, products per step, the brands Taobao lists for each keyword with their listing counts, the attribute values, and the exchange rate used.

### Data fields

| Field | Description |
|---|---|
| `itemId`, `url`, `taobaoUrl` | Stable numeric item ID, public catalogue page, canonical Taobao product page |
| `title`, `titleEn` | Original Chinese title; `titleEn` only when Taobao itself publishes an English title (rare) |
| `price`, `currency` | Current price in yuan (CNY) as a number (promotional price when a promotion runs) |
| `priceConverted`, `convertedCurrency` | `price` converted with the ECB daily reference rate |
| `priceHkd`, `priceTwd` | Taobao's own HKD and TWD prices |
| `promotionLabel`, `freeShipping`, `areaLimited` | Promotion name, shipping flags |
| `shopId`, `shopName`, `shopUrl` | Seller shop (no personal seller account data) |
| `descriptionMatchScore`, `shopServiceScore`, `shopDeliveryScore` | Shop scores (1-5); service/delivery only for shop queries |
| `categoryId`, `rootCategoryId` | Taobao category IDs (usable as `categoryIds` input) |
| `image`, `sellingPoints`, `reviewTags` | Main image, seller highlights, review tag counts when published |
| `query`, `queryType`, `queryTotalResults` | What found the product and how many listings Taobao reports for it |
| `searchRank`, `foundBy` | Position (1-40) in Taobao's ranking for the query (empty for products found by refinements) and the coverage step that found the product |

### Pricing

Pay per result: **$2.00 per 1,000 products** ($0.002 per product). No start fee, no monthly fee. Only products written to the dataset are charged. Duplicates, products outside your price filter and failed requests cost nothing. The run stops cleanly when your maximum charge is reached.

### Tips

- Use **Chinese keywords**. Taobao is a Chinese catalogue and English keywords match far fewer products.
- 100-500 products per keyword is the sweet spot. Higher limits go deeper into niche brands and attribute values; turn the refinements off if you only want the products Taobao ranks for the exact keyword.
- Feed `categoryId` or `shopId` values from one run into the next run to drill down.
- For rank tracking, schedule the same keywords daily with `maxItemsPerQuery` 40 and refinements off, then compare `searchRank`.
- Categories return about 20 products and shops up to 60 per run on Apify's default (US) proxy. For broader coverage, search the category's product type as a keyword.

### FAQ

**Why are there no SKUs, stock levels, full image galleries or full reviews?** Those live on Taobao's logged-in product pages and app APIs, which this Actor deliberately does not touch. It returns only what the public catalogue shows.

**Can I tell Tmall products from Taobao products?** Not reliably: the public catalogue lists both together without a platform label. `taobaoUrl` opens either kind (Taobao may ask you to sign in to view it).

**Why can `price` differ from the product page?** The catalogue shows the current (often promotional) price of the default variant. Prices of other variants can be higher. Some sellers use placeholder prices such as 99999 CNY; filter them with `maxPrice`.

**Do I need a Taobao account or proxies?** No account. Apify's datacenter proxy is enabled by default and usually enough.

**Is it legal?** The Actor only reads pages Taobao publishes for crawlers and allows in its robots.txt, at a polite rate, and it does not collect personal data. You are responsible for how you use the data. This unofficial tool is not affiliated with Taobao, Tmall or Alibaba Group.

**Something broke?** Taobao can change its catalogue without notice. Open an issue with your input and we will look at it quickly.

# Actor input Schema

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

Products to search for, one keyword per line. Chinese keywords give by far the best results (e.g. `机械键盘`, `手机壳`, `连衣裙`); common English words (`keyboard`, `iphone case`) also work, many English phrases do not. You can also paste a `www.taobao.com/list/product/<keyword>.htm` URL.

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

Optional. Taobao category IDs (e.g. `110210` for keyboards) or `www.taobao.com/list/category/<id>.htm` URLs. The `categoryId` field of any product in the output is such an ID. A category page lists 20 products (up to about 100 when sort orders are available for your proxy).

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

Optional. Taobao shop IDs (the `shopId` field of any product), `www.taobao.com/list/dianpu/<id>.htm` URLs, `shop<id>.taobao.com` URLs or any link containing `shopId=<id>`. Store links that show a name instead (like `brand.tmall.com`) cannot be used - search the store name as a keyword first and copy the `shopId` from any product row. Returns the up to 60 products on the shop's catalogue page plus the shop's service and delivery scores.

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

Maximum number of unique products to return for each keyword, category or shop. One Taobao catalogue page shows only 20-40 products and has no next page, so larger numbers are reached through brand and attribute refinements (see below). A keyword typically yields a few hundred to about 1,000 unique products; categories about 20 and shops up to 60 (more when sort orders are available).

## `refineByBrand` (type: `boolean`):

Keywords only. Also search `<brand> <keyword>` for up to 30 brands that Taobao lists for the keyword (most listings first). Each refined keyword adds up to 40 new products. Products found this way are marked in `foundBy`, e.g. `brand: 罗技`.

## `refineByAttribute` (type: `boolean`):

Keywords only. After the brands, also search `<value> <keyword>` for up to 30 attribute values Taobao lists for the keyword (for example switch types `青轴`, `红轴` for keyboards). Marked in `foundBy`, e.g. `attribute: 青轴`.

## `splitByPriceBands` (type: `boolean`):

Taobao honours sort and price-range parameters only for some client regions (not for US IPs, which Apify Proxy uses by default). When the Actor detects that they work for your proxy, it also queries every sort order and automatically chosen CNY price bands. Has no effect otherwise.

## `minPrice` (type: `integer`):

Optional. Only return products priced at or above this many yuan (CNY). Products outside the range are dropped and not charged.

## `maxPrice` (type: `integer`):

Optional. Only return products priced at or below this many yuan (CNY). Products outside the range are dropped and not charged.

## `convertPricesTo` (type: `string`):

Adds `priceConverted` in this currency next to the original CNY `price`, using the European Central Bank's daily reference rate (free, official; loaded once per run). Choose `NONE` to skip.

## `deduplicateAcrossQueries` (type: `boolean`):

If the same product matches several keywords, categories or shops, return (and charge) it only once - for the first query that found it.

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

Apify Proxy (datacenter) is used by default; the proxy session (IP) rotates every 30 requests and after any blocked response. The catalogue usually works without a proxy too.

## Actor input object example

```json
{
  "keywords": [
    "机械键盘"
  ],
  "maxItemsPerQuery": 50,
  "refineByBrand": true,
  "refineByAttribute": true,
  "splitByPriceBands": true,
  "convertPricesTo": "USD",
  "deduplicateAcrossQueries": true,
  "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": [
        "机械键盘"
    ],
    "maxItemsPerQuery": 50,
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("kyungminlee/taobao-catalog-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": ["机械键盘"],
    "maxItemsPerQuery": 50,
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("kyungminlee/taobao-catalog-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": [
    "机械键盘"
  ],
  "maxItemsPerQuery": 50,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call kyungminlee/taobao-catalog-scraper --silent --output-dataset

```

## MCP server setup

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