# Taobao Seller Catalog Scraper (`khadinakbar/taobao-seller-catalog-scraper`) Actor

Scrape a public Taobao or Tmall seller catalog from world.taobao.com/dianpu shop pages. One row per listing: item ID, title, CNY price, shop meta, Tmall flag, image, URL. First-screen public catalog only. Empty shops are VALID_EMPTY; blocks fail honestly. $0.004 per product.

- **URL**: https://apify.com/khadinakbar/taobao-seller-catalog-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 $4.00 / 1,000 seller catalog product scrapeds

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 Seller Catalog Scraper — Shop Products, Prices & Images

Turn a Taobao or Tmall **shop ID** or `world.taobao.com/dianpu` URL into **one dataset row per public catalog listing**, with item ID, title, CNY price, shop meta, Tmall flag, image, and item URL. This Actor reads the crawlable overseas storefront catalog 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 seller catalogs:

- Sourcing and merchandising teams that already have a shop ID from search and need the storefront's visible product cards.
- Competitive catalog checks on a known seller without opening every product detail page.
- AI agents that call a bounded shop-catalog tool through [Apify MCP](https://mcp.apify.com) and read the dataset plus `OUTPUT`.

When you need keyword search first, start with [Taobao Tmall Search Scraper](https://apify.com/khadinakbar/taobao-tmall-search-scraper) (it already emits `shopUrl` → `dianpu/{shopId}`), then pass the shop into this Actor. For full product detail (description, variants, ratings), continue with [Taobao Product Detail Scraper](https://apify.com/khadinakbar/taobao-product-detail-scraper).

### Practical scenario

A buyer found shop `63978904` during keyword research. They run this Actor with that shop URL, `sortBy: "sales"`, and `maxItemsPerSeller: 3`. The dataset returns the top visible catalog cards with title, priceCny, shopName, imageUrl, and url. They export CSV and open selected item URLs in the detail sibling.

### Input

#### Input fields

| Field | Type | What it controls |
|---|---|---|
| `shopUrls` | array | `https://world.taobao.com/dianpu/{shopId}.htm` storefront URLs. Prefill: live demo shop. |
| `shopIds` | array | Numeric shop IDs (same as dianpu pages). |
| `maxItemsPerSeller` | integer | Cap per shop. Prefill 3, default 40. First-screen only. |
| `maxResults` | integer | Run-wide billed-row cap. Prefill 3, default 120. |
| `sortBy` | enum | `sales`, `relevance`, `newest`, `credit`, `priceAsc`, `priceDesc`. |
| `tmallOnly` | boolean | Keep Tmall-flagged cards only. |
| `minPrice` / `maxPrice` | number | CNY bounds after extraction. |
| `expandSorts` | boolean | Re-query the shop across sorts and merge unique item IDs. |
| `proxyConfiguration` | object | Apify Proxy default for cloud runs. |

#### Quick start input

```json
{
  "shopUrls": ["https://world.taobao.com/dianpu/63978904.htm"],
  "maxItemsPerSeller": 3,
  "maxResults": 3,
  "sortBy": "sales"
}
```

### What data you receive

One default-dataset record is one public catalog 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 |
| `shopId` / `shopName` / `shopUrl` | Storefront identity |
| `sellerId` | Public seller id when exposed |
| `imageUrl` | Primary image |
| `url` | world.taobao.com item URL |
| `scrapedAt` | ISO 8601 collection time |

#### Illustrative output record

```json
{
  "itemId": "8803330176",
  "itemIdStr": "abcItemSlug",
  "title": "Example bottled water 4L x4",
  "url": "https://world.taobao.com/item/abcItemSlug.htm",
  "taobaoUrl": "https://item.taobao.com/item.htm?id=8803330176",
  "platform": "taobao",
  "isTmall": false,
  "priceCny": 45,
  "currency": "CNY",
  "shopId": "63978904",
  "shopName": "Example Shop",
  "shopUrl": "https://world.taobao.com/dianpu/63978904.htm",
  "imageUrl": "https://img.alicdn.com/imgextra/example.jpg",
  "sortBy": "sales",
  "position": 1,
  "scrapedAt": "2026-09-29T13:00:00.000Z"
}
```

### Pricing

Billing is **Pay per event** with **Apify platform usage included**. 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 |
| Catalog product | $0.004 | Each validated listing saved to the dataset |

Filter-dropped rows are unbilled. `maxItemsPerSeller` / `maxResults` are the event-cost ceiling: 3 products are about $0.012 plus the start event, with Apify platform usage included.

### Honest limits

- Public **first-screen** `world.taobao.com/dianpu` cards only. `dianpu/{id}_N.htm` pagination returns a homepage shell and is **not** scraped as extra pages.
- Mainland `shop*.taobao.com` hosts and login-walled storefronts are out of contract.
- Empty or unknown shops finish `VALID_EMPTY` with zero catalog charges. Anti-bot walls fail as `UPSTREAM_FAILED`.

### Use through the API

```bash
curl "https://api.apify.com/v2/acts/khadinakbar~taobao-seller-catalog-scraper/runs" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "shopUrls": ["https://world.taobao.com/dianpu/63978904.htm"],
    "maxItemsPerSeller": 3,
    "maxResults": 3,
    "sortBy": "sales"
  }'
```

### Agent prompt card

```text
Use khadinakbar/taobao-seller-catalog-scraper with shopUrls or shopIds for a public world.taobao.com storefront.
Keep maxItemsPerSeller small for tests. Read dataset rows plus OUTPUT.outcome.
Do not expect full shop inventory — first-screen catalog only.
```

### FAQ and responsible use

Use this Actor only on public catalog pages you are allowed to access. Respect Taobao/Tmall terms, robots rules, and applicable law. This tool returns public listing cards, not private seller contacts or login-only inventory. Open the Issues tab for feedback or custom work requests.

### Builder's note

Day-0 probing confirmed the same embedded `itemListModuleResponse` JSON used by the search sibling works on live dianpu pages, while `_N.htm` “pagination” URLs do not. Shipping an honest first-screen contract beats claiming full-shop coverage that the public overseas surface does not provide.

# Changelog

This Actor's version history is a separate document: https://apify.com/khadinakbar/taobao-seller-catalog-scraper/changelog.md

# Actor input Schema

## `shopUrls` (type: `array`):

Public world.taobao.com/dianpu/{shopId}.htm storefront URLs. One shop per entry. Prefill uses a known live shop. Product-detail URLs and mainland shop\*.taobao.com hosts are rejected.

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

Numeric Taobao shop IDs. Equivalent to opening https://world.taobao.com/dianpu/{id}.htm. Use this when you already have shopId from a search sibling row.

## `maxItemsPerSeller` (type: `integer`):

Hard cap on billed catalog rows for each shop. The public first-screen page usually exposes about 40–60 cards; dianpu/\_N.htm pagination is a homepage shell and is not scraped. Prefill 3 keeps quality tests cheap.

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

Hard cap on billed rows across every shop in the run. Stops once this many valid listings are saved. Defaults to 120.

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

Order used on the shop catalog page. sales is sales ranking. relevance is comprehensive. newest is new arrivals. credit ranks by seller credit. priceAsc and priceDesc sort by displayed CNY price.

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

When true, keep only listings whose title or shop name marks them as Tmall (天猫/天貓). Filtered rows are not billed.

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

Drop listings whose displayed yuan price is below this amount. Unknown prices are dropped when a bound is set.

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

Drop listings whose displayed yuan price is above this amount. Unknown prices are dropped when a bound is set.

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

The public dianpu first screen is capped. Enable this to re-query the same shop across sales, relevance, newest, credit, and price sorts and merge unique item IDs until maxItemsPerSeller. Off by default to keep MCP and test runs cheap.

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

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

## Actor input object example

```json
{
  "shopUrls": [
    "https://world.taobao.com/dianpu/63978904.htm"
  ],
  "shopIds": [
    "63978904"
  ],
  "maxItemsPerSeller": 3,
  "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 seller catalog listing.

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

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

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

Input coverage, provider route, shop-catalog 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 = {
    "shopUrls": [
        "https://world.taobao.com/dianpu/63978904.htm"
    ],
    "maxItemsPerSeller": 3,
    "maxResults": 3
};

// Run the Actor and wait for it to finish
const run = await client.actor("khadinakbar/taobao-seller-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 = {
    "shopUrls": ["https://world.taobao.com/dianpu/63978904.htm"],
    "maxItemsPerSeller": 3,
    "maxResults": 3,
}

# Run the Actor and wait for it to finish
run = client.actor("khadinakbar/taobao-seller-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 '{
  "shopUrls": [
    "https://world.taobao.com/dianpu/63978904.htm"
  ],
  "maxItemsPerSeller": 3,
  "maxResults": 3
}' |
apify call khadinakbar/taobao-seller-catalog-scraper --silent --output-dataset

```

## MCP server setup

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