# Taobao Tmall Search Scraper (`khadinakbar/taobao-tmall-search-scraper`) Actor

Search public Taobao and Tmall listings by keyword or world.taobao.com product/category URL. Returns one row per product: item ID, title, CNY price, shop, Tmall flag, image, URL. Uses the crawlable overseas catalogue. Empty matches are VALID\_EMPTY; blocks fail honestly. $0.005 per product.

- **URL**: https://apify.com/khadinakbar/taobao-tmall-search-scraper.md
- **Developed by:** [Khadin Akbar](https://apify.com/khadinakbar) (community)
- **Categories:** E-commerce, Lead generation, MCP servers
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 taobao/tmall 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?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Taobao Tmall Search Scraper — Product Listings, Prices & Shops

Turn a Taobao or Tmall keyword into **one dataset row per public catalogue listing**, with item ID, title, CNY price, shop, Tmall flag, image, and item URL. This Actor reads the crawlable world.taobao.com product and category catalogue over HTTP on Apify, with proxy rotation, scheduling, API access, and MCP-ready output.

Taobao and Tmall are trademarks of their respective owners. This independent Actor is not affiliated, associated, or endorsed by Alibaba Group, Taobao, or Tmall.

### Best fit for this Actor

This Actor is designed as a focused standalone workflow for public Taobao and Tmall catalogue search:

- Product researchers who start with a keyword such as `iphone` or `机械键盘` and want listing cards with price and shop.
- Sourcing workflows that keep Tmall-flagged storefronts by setting `tmallOnly`.
- AI agents that call a bounded search tool through [Apify MCP](https://mcp.apify.com) and read the dataset plus `OUTPUT`.

When the same research job needs Alibaba B2B supplier cards instead of Taobao retail listings, start with [Alibaba Listings Scraper](https://apify.com/khadinakbar/alibaba-listings-scraper) then compare MOQ and supplier years. For AliExpress retail search cards, pair this Actor with [AliExpress Product Search Scraper](https://apify.com/khadinakbar/aliexpress-product-search-scraper) after you have a Taobao price baseline.

### Practical scenario

A merchandiser is checking iPhone catalogue prices before a sourcing call. They start with `searchQueries: ["iphone"]`, `sortBy: "sales"`, and `maxResults: 3`. The Actor returns rows with title, priceCny, isTmall, shopName, imageUrl, and url. They then export CSV and pass the item URLs into a detail workflow.

### Input

#### Input fields

| Field | Type | What it controls |
|---|---|---|
| `searchQueries` | array | Keywords, one per query. Chinese keywords usually match more of the catalogue. Prefill: `iphone`. |
| `startUrls` | array | Optional world.taobao.com `/product/{keyword}.htm` or `/category/{id}.htm` pages. |
| `maxResults` | integer | Hard cap on billed rows. Prefill 3, default 40, maximum 2000. |
| `sortBy` | enum | `sales`, `relevance`, `credit`, `priceAsc`, or `priceDesc`. |
| `tmallOnly` | boolean | Keep listings whose title or shop name marks them as Tmall. |
| `minPrice` / `maxPrice` | number | CNY bounds applied after extraction. |
| `expandSorts` | boolean | Re-query the keyword across sort orders and merge unique item IDs. |
| `proxyConfiguration` | object | Apify Proxy is the default cloud route. |

#### Quick start input

```json
{
  "searchQueries": ["iphone"],
  "maxResults": 3,
  "sortBy": "sales"
}
```

### What data you receive

One default-dataset record is one public catalogue card. You can download the dataset in JSON, HTML, CSV, or Excel.

| Field | Description |
|---|---|
| `itemId` | Numeric item identifier |
| `title` | Listing title |
| `priceCny` | Displayed yuan price |
| `currency` | ISO currency, usually CNY |
| `isTmall` / `platform` | Tmall badge from public title or shop |
| `shopName` / `shopUrl` | Storefront on the card |
| `imageUrl` | Primary image |
| `url` | world.taobao.com item URL |
| `searchQuery` | Keyword or category context |
| `scrapedAt` | ISO 8601 collection time |

#### Illustrative output record

```json
{
  "itemId": "974671890820",
  "itemIdStr": "abcItemSlug",
  "title": "Apple iPhone 17",
  "url": "https://world.taobao.com/item/abcItemSlug.htm",
  "taobaoUrl": "https://item.taobao.com/item.htm?id=974671890820",
  "platform": "tmall",
  "isTmall": true,
  "priceCny": 5999,
  "currency": "CNY",
  "shopName": "Example Tmall Store",
  "imageUrl": "https://img.alicdn.com/imgextra/example.jpg",
  "searchQuery": "iphone",
  "sortBy": "sales",
  "position": 1,
  "scrapedAt": "2026-09-10T13:30:00.000Z"
}
```

### Pricing

Billing is **Pay per event** plus **platform usage**. Confirm the live unit prices on the Actor **Pricing tab** before a large run.

| Event | Price | When it fires |
|---|---|---|
| Actor start | $0.00005 | Once per run |
| Product scraped | $0.005 | Each validated listing saved to the dataset |

Filter-dropped rows are unbilled. `maxResults` is the event-cost ceiling: 3 products are about $0.015 plus start and platform usage; 40 products are about $0.20 plus start and platform usage.

### Use through the API

```bash
curl "https://api.apify.com/v2/acts/khadinakbar~taobao-tmall-search-scraper/runs" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"searchQueries":["iphone"],"maxResults":3,"sortBy":"sales"}'
```

Read default dataset items after the Actor reaches a terminal status.

### Use with AI agents through Apify MCP

> Search public Taobao and Tmall catalogue listings for the keyword iphone, keep at most 3 products, return title, CNY price, shop, Tmall flag, image, and item URL, then report the run outcome and dataset.

Inspect `OUTPUT` for the outcome, read the dataset rows, keep source URLs as provenance, and respect `maxResults` as the cost control. Connect through [Apify MCP](https://mcp.apify.com) for the current client setup.

### Best results and workflow guidance

- Start with a specific product keyword and a small `maxResults` to confirm the catalogue shape.
- Use Chinese keywords when you need mainland-style coverage of the public catalogue.
- Provide a world.taobao.com `/product/` or `/category/` URL when you already have a catalogue page.
- Turn on `tmallOnly` when the job is official-storefront comparison.
- Pair a completed search with a product-detail Actor when you need specs beyond the listing card.
- Confirm the Pricing tab and platform usage before expanding `expandSorts`.

The public catalogue serves about 40 unique products per keyword and sort. Empty matches finish as a completed empty dataset. Catalogue pages that stay unavailable finish with an upstream outcome so you can retry with a residential proxy route.

### Builder's note

I built this as a search-only SKU after I found that the public world catalogue embeds `itemList` JSON that HTTP Chrome-TLS can read, while mainland search stays behind a separate gate. My goal is a cheap MCP tool that returns honest listing cards with collection time and source URLs, then routes detail work to a sibling Actor.

### Responsible use

Use this Actor only on public catalogue pages you are authorized to access, and in line with applicable laws and the site terms of service. Keep personal data out of the workflow unless you have a lawful basis. This Actor is provided for legitimate product research, price monitoring, and sourcing.

# Actor input Schema

## `searchQueries` (type: `array`):

Taobao/Tmall keywords to search, one entry per query (e.g. iphone, 机械键盘, 口红). Chinese keywords usually match more of the mainland catalogue. Each keyword opens one world.taobao.com/product page (~40 cards). This is not a product-detail URL.

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

Optional world.taobao.com /product/{keyword}.htm or /category/{id}.htm pages to scrape directly. Use this instead of, or together with, searchQueries. item.taobao.com and detail.tmall.com product URLs are ignored because this Actor is search-only.

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

Hard cap on billed product rows across every keyword and URL. The run stops once this many valid listings are saved. Defaults to 40 (about one catalogue page). At $0.005/product, 40 rows is $0.20 plus the $0.00005 start event.

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

Order used on the catalogue page. sales is Taobao sales ranking. relevance is comprehensive. credit ranks by seller credit. priceAsc and priceDesc sort by displayed CNY price. Applies to keyword searches.

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

When true, keep only listings whose title or shop name marks them as Tmall (天猫/天貓). Filtered rows are not billed. Leave false to return mixed Taobao C2C and Tmall results.

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

Drop listings whose displayed yuan price is below this amount. Applied after extraction; unknown prices are dropped when a bound is set. Leave empty for no minimum.

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

Drop listings whose displayed yuan price is above this amount. Applied after extraction; unknown prices are dropped when a bound is set. Leave empty for no maximum.

## `expandSorts` (type: `boolean`):

The public catalogue serves about 40 unique products per keyword and sort. Enable this to re-query the same keyword across sales, relevance, credit, and price sorts and merge unique item IDs until maxResults. Off by default to keep MCP and test runs cheap.

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

Proxy used for catalogue requests. Residential usually survives Taobao rate limits better than datacenter. Leave on Apify Proxy for cloud runs.

## Actor input object example

```json
{
  "searchQueries": [
    "iphone",
    "机械键盘"
  ],
  "startUrls": [
    "https://world.taobao.com/product/iphone.htm"
  ],
  "maxResults": 3,
  "sortBy": "sales",
  "tmallOnly": false,
  "expandSorts": false,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `dataset` (type: `string`):

Default dataset containing one structured record per public Taobao/Tmall search listing.

## `summary` (type: `string`):

Stable terminal outcome with persisted-item counts, charged events, and warnings.

## `runSummary` (type: `string`):

Input coverage, provider route, catalogue diagnostics, cost state, and safe errors for the completed run.

# 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 = {
    "searchQueries": [
        "iphone"
    ],
    "maxResults": 3
};

// Run the Actor and wait for it to finish
const run = await client.actor("khadinakbar/taobao-tmall-search-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 = {
    "searchQueries": ["iphone"],
    "maxResults": 3,
}

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

```

## MCP server setup

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