# Taobao Product Detail Scraper (`apt_marble/taobao-product-detail-scraper`) Actor

Turn any Taobao or Tmall link into a complete product record: title, price and promotion, buyer-rating split with a sample review, full image set, coupon link and seller record. Paste up to 500 links per run. No account, no login.

- **URL**: https://apify.com/apt\_marble/taobao-product-detail-scraper.md
- **Developed by:** [Hamza](https://apify.com/apt_marble) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$1.50 / 1,000 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 Product Detail Scraper

Get the full record behind any Taobao or Tmall product. Paste product links or
bare item IDs and each one comes back complete: title, price and promotion,
buyer-rating aggregates with a sample review, the seller record with its
service scores, images, coupon link and category path. No account and no login
are needed, and reads are direct and fast — no browser, nothing signed in.

### What you can do with it

- **Build a product database.** Turn a list of links into a structured catalog
  with prices, ratings and seller records attached.
- **Monitor prices and promos.** Re-run the same links on a schedule and watch
  prices and promotions change.
- **Quality-check before sourcing.** Buyer-rating aggregates plus a real sample
  review reveal what buyers think before you commit.
- **Audit sellers at a glance.** Every record carries the seller's scores,
  assortment size and years open, so candidates sort themselves.
- **Feed a store or spreadsheet.** Every field is a plain column — export to
  Excel, Google Sheets, CSV or JSON in one click.

### What you get

One row per product. Abridged real example:

```json
{
  "itemId": "730344766230",
  "title": "百億 農夫山泉純淨水...",
  "url": "https://world.taobao.com/item/730344766230.htm",
  "price": 49.9,
  "promoPrice": null,
  "currency": "CNY",
  "location": "上海",
  "categoryPath": ["阿裏B2C商城", "進口食品館", "進口飲料", "礦泉水/純淨水"],
  "isTmall": false,
  "freeShipping": false,
  "couponUrl": "https://s.click.taobao.com/t?e=…",
  "ratingGoodPercent": 100,
  "reviewCountHint": "200+",
  "sampleReview": { "score": 5, "content": "農夫山泉已收到日期新鮮，包裝很好", "date": "2026.09.07 06:31", "buyer": "***", "variant": "商品規格:純淨水550ml*24瓶【12瓶*2箱】" },
  "imageUrl": "https://img.alicdn.com/imgextra/i3/393647717/O1CN01MpNlgy26sRW0tsXf1_!!393647717.jpg",
  "shopId": "63978904",
  "shopName": "優送網",
  "shopUrl": "https://world.taobao.com/dianpu/63978904.htm",
  "shopServiceScores": { "物流服務": 4.9, "服務": 4.9, "商品描述": 4.9 },
  "shopProductCount": 616,
  "shopOpenSince": "2010-12-16 18:29:42",
  "scrapedAt": "2026-09-21T00:00:00.000Z"
}
```

### Input reference

| Field | Type | Default | What it does |
| --- | --- | --- | --- |
| `productUrls` | list of text | *(example links)* | Product links (`world.taobao.com`, `item.taobao.com`, `detail.tmall.com`) or bare numeric item IDs. Up to 500 per run. |
| `maxConcurrency` | number | `5` | How many products to read at the same time (1–10). |

### Output fields

| Field | Type | Description |
| --- | --- | --- |
| `itemId` | text | The product's identifier on the site. |
| `title` | text | Product title. |
| `url` | text | Direct link to the product. |
| `price` | number | Current selling price, in yuan. |
| `promoPrice` | number | Discounted price while it differs from the selling price; empty otherwise. |
| `priceVaries`, `onPromo` | true/false | Whether the price spans a range, and whether a distinct promo price is active. |
| `currency` | text | Always `CNY`. |
| `location` | text | Where the product ships from, as the site prints it. |
| `categoryId`, `categoryPath` | text / list | The site's own category trail for this product. |
| `isTmall` | true/false | Whether this is a brand flagship / marketplace listing. |
| `freeShipping` | true/false | Whether the product ships free. |
| `couponUrl` | text | The coupon link the site publishes for this product, when there is one. |
| `ratingGoodPercent`, `ratingNeutralPercent`, `ratingBadPercent` | number | Buyer-rating split, exactly as the site publishes it. |
| `reviewCountHint` | text | The review volume band the site publishes (for example `200+`). |
| `sampleReview` | object | One published buyer review: score, text, date, masked buyer, purchased variant and photo. |
| `imageUrl`, `images` | text / list | Main picture and the full image set. |
| `shopId`, `shopName`, `shopUrl` | text | The seller behind the product and its link. |
| `shopServiceScores` | object | The seller's service scores by name, as the site publishes them. |
| `shopProductCount`, `shopNewProductCount` | number | The seller's assortment size and recent arrivals, when published. |
| `shopOpenSince` | text | When the seller opened, as the site prints it. |
| `sellerId` | text | The seller's identifier on the site. |
| `scrapedAt` | text | When the row was collected. |

### Pricing

You pay per product returned — nothing else, and nothing for a link that
points to a removed or unreadable item.

| What you pay for | Price |
| --- | --- |
| Each complete product record | $1.50 per 1,000 |

**Worked example.** A catalog of 400 products costs **$0.60**. A daily price
check on 200 products costs $0.30 per run.

### Limits & what this actor cannot do

- Removed, expired or otherwise unreadable items return no row and cost
  nothing. They are listed in the run summary so you can tell them apart from
  successful reads.
- Prices, promos, ratings and seller scores are a snapshot at the moment of
  collection and keep changing afterwards.
- Per-product sales totals, option matrices and stock figures are not
  published on this surface. They come back empty rather than estimated —
  only what the site prints is returned.
- Review volumes arrive as the site's own rounded bands (for example `200+`),
  and one sample review is included per product rather than the full history.
- Speed depends on the size of the job and on the source site's own response
  times; no fixed throughput is promised.
- The source site's terms govern automated access. You are responsible for
  using the data lawfully and in line with those terms, and for handling any
  personal data in line with applicable privacy law.

### FAQ

**Do I need a Taobao account?**
No. Nothing is signed in to and nothing is bought.

**Which links work?**
Any `world.taobao.com/item/`, `item.taobao.com/item.htm` or
`detail.tmall.com/item.htm` product link — or just the numeric item ID on
its own.

**What happens with a dead link?**
It returns no row, costs nothing, and is named in the run summary under
failures so you can clean your list.

**Can I schedule price checks?**
Yes. Save your links as a task and run it on any schedule Apify supports,
then compare prices and promos over time.

**Why is there only one sample review?**
Because the product surface publishes rating aggregates plus one featured
review. It is returned whole — score, text, date, variant and photo — but it
is a sample, not the full review history.

# Actor input Schema

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

How many products to read at the same time. Higher is faster; lower is gentler on the source site.

## `productUrls` (type: `array`):

Product links (world.taobao.com, item.taobao.com, detail.tmall.com) or bare numeric item IDs. Up to 500 per run.

## Actor input object example

```json
{
  "maxConcurrency": 5,
  "productUrls": [
    "https://world.taobao.com/item/730344766230.htm"
  ]
}
```

# Actor output Schema

## `products` (type: `string`):

Every product you asked for, as a complete record.

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

Counts per product, including any item that could not be read.

# 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 = {
    "maxConcurrency": 5,
    "productUrls": [
        "https://world.taobao.com/item/730344766230.htm"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("apt_marble/taobao-product-detail-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 = {
    "maxConcurrency": 5,
    "productUrls": ["https://world.taobao.com/item/730344766230.htm"],
}

# Run the Actor and wait for it to finish
run = client.actor("apt_marble/taobao-product-detail-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 '{
  "maxConcurrency": 5,
  "productUrls": [
    "https://world.taobao.com/item/730344766230.htm"
  ]
}' |
apify call apt_marble/taobao-product-detail-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,apt_marble/taobao-product-detail-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/BDHcpPgcCR8H2cTMY/builds/4D7E6Wwab2Hl7c3Mp/openapi.json