Taobao & Tmall Scraper — Products, Search, Reviews & Q&A 🛍️

🎉 Five scrapers in one — keyword search, product details (standard & premium final-price), shop catalogs, reviews, and buyer Q&A

Built for dropshippers, sourcing teams, e-commerce analysts, and anyone who needs clean Taobao data without the setup headache

---

🔎 What is the Taobao & Tmall Scraper — and when should you use it?

The Taobao & Tmall Scraper turns an item ID, a search keyword or a seller ID into clean, structured rows you can filter, export and feed straight into a spreadsheet, database or AI agent. No Taobao account, no portal API key, no browser automation to keep alive.

Use it when you need: retail prices in yuan, coupon-adjusted final prices, SKU variants and stock, sales counts, seller and shop identity, product images and video, customer reviews with photos, and buyer questions with their answers.

Use something else when: you are sourcing from factories rather than buying at retail. Wholesale listings carry bulk pricing and minimum order quantities that consumer pages never show. Use the 1688 Wholesale Scraper for that side of the market.

---

🤖 Use with AI agents

Already connected to the Apify MCP server? Just ask for this Actor by name: sian.agency/taobao-tmall-product-scraper

Your agent can pay for its own runs. This Actor is eligible for agentic payments, so an agent can discover it, run it and settle the bill over x402 (USDC on Base) or Skyfire — without an Apify account or API token of its own. Billing is the same either way: per successful row, never for errors.

Otherwise copy this prompt into Claude, ChatGPT, Cursor or any MCP-enabled assistant:

I want to research products on Taobao and Tmall using the Apify Actor `sian.agency/taobao-tmall-product-scraper`.

Use it when I need: retail prices in yuan, final coupon-adjusted prices, SKU variants and
stock, sales counts, shop and seller details, product images, customer reviews, or the
questions buyers asked before ordering.

Don't use it when: I am sourcing wholesale from factories and need bulk pricing or minimum
order quantities — use `alibaba-1688-wholesale-scraper` instead.

How to call it: pick ONE `operation` per run.
- `keywordSearch` takes a `keyword`, plus optional `startPrice`, `endPrice`, `tmallOnly`,
  `sort` and `maxPages`.
- `productDetail` takes an `itemId` and a `detailVersion` (`v1` standard, `v9` full,
  `v4` premium final/coupon pricing).
- `productDetailAlt` takes an `itemId`, and reads a different catalogue when
  `productDetail` cannot find the item.
- `shopCatalog` takes a `userId`, plus a `shopId` when `catalogVersion` is `v2` or `v3`.
- `productReviews` takes an `itemId` and an `orderType`.
- `productQuestions` takes an `itemId`.

Start with this input:
{
  "operation": "keywordSearch",
  "keyword": "无线耳机",
  "tmallOnly": true,
  "maxPages": 3
}

Ask me which keyword, product or shop to start from, then run the Actor and summarise the
results as a table.

Things you can ask your agent for:

• "Find the best-selling wireless earbuds on Tmall under 200 yuan and show me price, sales and shop."
• "Pull this seller's whole catalogue, then flag the products that undercut my own listing."
• "Read the reviews for this item and tell me what buyers complain about most."

Machine-readable API, MCP config and OpenAPI definition for this Actor are published at apify.com/sian.agency/taobao-tmall-product-scraper.md.

---

📋 Overview

Pulling Taobao and Tmall data by hand, or keeping your own scraper alive? This actor returns structured rows from both, one clean run per task and one tidy dataset out.

What you get:

• ✅ Five operations, one actor: Keyword search, product detail, shop catalog, reviews, and buyer Q&A — pick what you need
• ⚡ 90+ structured fields: Every response pre-flattened into a flat row — no parsing nested Chinese JSON
• 🎯 Production-ready output: Predefined dataset views for instant BI integration
• 💰 Pay-per-result: You're charged for rows you actually receive, never for errors
• 💎 No account, no API key, no setup: Just paste an item ID or keyword and run — works out of the box
• ✨ NEW — Premium detail: the exact after-coupon final payable price per product and per SKU — for precise margin and re-pricing math
• ✨ NEW — Buyer Q&A: real pre-purchase questions and answers, plus the top buyer-concern tags for any product

---

✨ Features

• 🔍 Keyword Search: Search Taobao and Tmall by query (Chinese, English, or mixed) with optional price range, Tmall-only filter, and sort order
• 🛍️ Product Detail: Full product payload — SKUs, pricing tiers, coupons, attributes, specs, and promotion info
• 💎 Premium Detail (final pricing): the exact after-coupon final payable price per product and per SKU — the truest number for margin and re-pricing math
• 🏪 Shop Catalog: Pull a seller's full product list — quick scans (30 items/page) or deep sweeps (60 items/page) with price, hot, and new-arrivals sorting
• 💬 Review Scraping: Customer reviews with text, photos, videos, purchased variant, reviewer info, follow-up comments, and sort-by-date or sort-by-relevance
• ❓ Buyer Q&A: real pre-purchase questions and answers per product, plus the top buyer-concern tags
• 🔄 Product Detail — Alternate Source: the same lookup from a different source, for products the standard versions cannot return — compact flat row with price, CNY price, stock, per-SKU variants, images and brand
• 🎨 SKU Variant Intelligence: Per-SKU prices, stock levels, property paths, and swatch images for every color/size combo
• 📊 Three Dataset Views: Overview (mixed), Products (search/catalog/detail), Reviews — switch views without re-running
• 🎬 Media Included: Product videos, description gallery, review photos and videos — all as direct URLs
• 🌏 Chinese + English Titles: Search results include machine-translated English titles where available
• 📄 Paginated Operations: Keyword Search, Shop Catalog, and Reviews all paginate automatically — set maxPages to control scope
• 🔀 Sort Options: Sort search results by sales, price, or relevance; sort shop catalogs by comprehensive, hot selling, new arrivals, or price

---

🕒 Data freshness & detail versions

Every row carries a recordTime field — the timestamp the data was actually captured. Use it (not _fetchedAt, which is just when this run executed) to verify how fresh each row is.

For Product Detail, the detailVersion you choose decides freshness:

detailVersion	Label	Freshness	What you get	When to use
v3 (default)	⭐ Recommended	Fresh — live, non-cached	Flat, easy-to-map payload: title, current price, stock (totalStock) and units sold (soldCount), full image gallery, SKU table, shop and brand, description HTML, plus detail_url, delist_time, video and location. recordTime = true capture time.	The default. Fastest, most consistently available, and the only version that fills every curated field. Start here.
v1	🔋 Standard	Fresh — live, non-cached	The richest classic payload: item, price block (list / promotion / HK+TW exchange rates), full SKU lists, specifications (groupProps), description HTML, and the seller/shop block. recordTime = true capture time.	When you need the list-vs-sale price spread (originalPrice ≠ discountPrice) or the groupProps spec table. ⚠️ Its promotion block can describe an expired campaign — check startTime / endTime before trusting discountPrice. Leaves totalStock and soldCount empty.
v9	🆕 Full	Fresh — live, non-cached	Flat response — every field at the top level — plus mainItemInfo with after-coupon pricing. recordTime = true capture time.	A cross-check, or when an item resolves here and nowhere else. ⚠️ Its stock/sold/price fields are rounded display strings ("1万+", "239.00-269.00"), so totalStock, soldCount and discountPrice are deliberately left empty rather than reported wrongly — read num, totalCount and price as text if you need them.
v4 💎	Premium	Fresh — live, non-cached	The final payable price per product and per SKU (finalPriceYuan, finalSkuPriceYuan, sku2info, skuBase) — after-coupon campaign pricing.	When accurate checkout pricing is the priority. Billed at the premium per-row rate.
v5	⚡ Lite	RETIRED	No longer available. Still accepted only so existing saved tasks keep running — such a run is served by v3 Recommended instead (fresher, different field names).	Don't pick it for new work.

Search, Shop Catalog, Reviews, and Q&A are all live (non-cached) and stamped with a true-capture recordTime.

🔄 Automatic fallback — read this before pinning a field

The standard versions (v3 / v1 / v9) cover different products: an item one version cannot return often resolves on another. So detailVersion is a preference, not a guarantee — if your pick cannot serve the item, the actor tries the others in order (v3 → v1 → v9) and returns whichever answers.

Build your pipeline on the curated fields. These carry the same name and meaning on every version, so a fallback never breaks your mapping:

itemId · title · shopId · pictUrls · totalStock · soldCount · originalPrice · discountPrice · itemDescHtml · recordTime · _operation · _fetchedAt · _page · _sourceItemId · status

They are populated at different rates, though — measured on 7 products all three versions answered (2026-08-26):

Curated field	v3 ⭐	v1 🔋	v9 🆕
itemId · title · shopId · pictUrls · itemDescHtml · recordTime	7/7	7/7	7/7
originalPrice · discountPrice	7/7	7/7	—
totalStock · soldCount	7/7	—	—

The raw fields underneath differ a lot (v3 gives num_iid / skus / props_list; v1 gives item / itemPrice / skuPropertyList; v9 gives item_imgs / specs / mainItemInfo) — see the field matrix before pinning one.

The 💎 Premium version is never substituted in either direction: ask for v4 and you get v4 or an error row — a standard request can never be silently upgraded into premium billing.

ℹ️ About v2: an older v2 "async premium" detail version is not available through this actor, and cannot be. It is served only as an offline batch job — submit a task, wait, download a file — and returns no data when requested directly, so it cannot be delivered in a run. Previous versions of this README suggested picking v2 under detailVersion; that was never selectable. Use v4 for premium final pricing.

---

🔄 Product Detail — Alternate Source

A separate operation, not a detailVersion. It answers the same question — "give me this product" — from a different source, so its coverage differs. Reach for it when Product Detail returns "This item is not supported" or cannot serve an item: in testing it returned products the standard versions could not.

Billed at the same per-result rate as Product Detail — it is a coverage option, not an upsell.

curl -X POST "https://api.apify.com/v2/acts/sian.agency~taobao-tmall-product-scraper/runs?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"operation": "productDetailAlt", "itemId": "744983869996"}'

Field	What it gives you
title · itemId · detailUrl	identity — the two fields shared with Product Detail, plus a canonical URL
price · priceCNY · originalPrice	current and pre-discount price
totalStock	units available across all SKUs
skuVoList	per-variant price, stock and properties
images · mainImg · description	media and description markup
brandName · brandId · tagList	brand and merchandising tags

Use the Alternate Source dataset view for the curated subset.

⚠️ Different field set from Product Detail — by design. It comes from a different source with its own shape, so it does not return the Product Detail columns (skuPropertyList, itemDescHtml, groupProps, …), and Product Detail does not return these. Filter on _operation to tell the two apart. Only itemId and title are stable across both.

itemId is stamped from your input and detailUrl is rebuilt, because this source returns neither.

This source also carries import-oriented fields — exchangeRate, expressFee, startQuantity (MOQ) and batchPrice (tier pricing). They were empty or trivial on every item we tested (batchPrice null, startQuantity 1, expressFee 0), so treat them as best-effort: they are passed through when they are reported, and should not be relied on.

---

🎬 Quick Start

Run one operation, get one dataset. The operation selector drives the entire run — either search by keyword, look up a product by ID, dump a shop, or pull reviews.

curl -X POST "https://api.apify.com/v2/acts/sian.agency~taobao-tmall-product-scraper/runs?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"operation": "productDetail", "itemId": "744983869996", "detailVersion": "v1"}'

---

🎯 Which Operation Should I Use?

I want to...	Use this
Get full details for one product (SKUs, images, coupons, specs)	Product Detail → v1 Standard (fresh, default)
Find products by keyword with prices and ratings	Keyword Search → sort by sales or price
Dump a seller's full product catalog	Shop Catalog → extended (60 items/page)
Read customer reviews with photos and variants	Product Reviews → sort by date or relevance
Get the exact final payable price (after all coupons)	Product Detail → v4 💎 Premium
Read buyer questions, answers & top concerns	Product Q&A
Get a product the standard detail versions can't return	🔄 Product Detail — Alternate Source
Compare a competitor's shop pricing at scale	Shop Catalog → extended + sort by price
Find best-selling products in a category	Keyword Search → sort _sale
Build a brand's complete SKU map	Keyword Search → Shop Catalog (chain two runs)
Mine review language and photos for ad creative	Product Reviews → sort by feedbackdate

---

🚀 Getting Started (3 Simple Steps)

Step 1: Pick an Operation

Choose one of five modes in the operation dropdown: 🔍 Keyword Search, 🛍️ Product Detail, 🏪 Shop Catalog, 💬 Product Reviews, or ❓ Product Q&A.

Step 2: Provide the Key Input

• Product Detail / Reviews → an itemId (the number from any Taobao product URL after id=)
• Keyword Search → any keyword (Chinese, English, or mixed — e.g. "iphone 15" or "无线耳机")
• Shop Catalog → a userId (seller ID), and optionally shopId for extended catalog mode

Step 3: Run It

Click Start — the actor handles the rest. Paginated operations respect maxPages (default 5, max 50).

That's it! In under a minute, you'll have:

• A flat dataset with 90+ structured fields per row
• Every image, video, and variant URL as direct links
• Three ready-to-filter views for BI tools, Airtable, Google Sheets, or n8n

---

📥 Input Configuration

Field	Type	Required	Description
operation	enum	✅	keywordSearch (default) | productDetail | productDetailAlt | shopCatalog | productReviews | productQuestions
itemId	string	for productDetail, productReviews, productQuestions	Numeric Taobao/Tmall item ID
detailVersion	enum	v3	v3 Recommended (default, fresh) | v1 Standard (fresh, list-vs-sale spread) | v9 Full (fresh, flat) | 💎 v4 Premium (final/coupon pricing). See Data freshness & detail versions and the field matrix.
keyword	string	for keywordSearch	Search query — supports Chinese, English, mixed
startPrice	integer	—	Min price in CNY (keywordSearch only)
endPrice	integer	—	Max price in CNY (keywordSearch only)
tmallOnly	boolean	—	Restrict search to Tmall brand stores
sort	enum	—	Sort order — sales, price ↑↓, comprehensive, hot, new arrivals
userId	string	for shopCatalog	Numeric seller / user ID
shopId	string	for extended shopCatalog	Shop ID (required for extended catalog modes)
catalogMode	enum	—	standard (30 items/page) | extended (60 items/page) | latest
orderType	enum	—	Review sort: feedbackdate (by date) or general (by relevance)
maxPages	integer	—	Pages to fetch (1–50, default 5)

Example — Product Detail (fresh Full version with coupon pricing)

{
  "operation": "productDetail",
  "itemId": "744983869996",
  "detailVersion": "v1"
}

Example — Keyword Search with price filter and sort

{
  "operation": "keywordSearch",
  "keyword": "sony headphones",
  "startPrice": 500,
  "endPrice": 3000,
  "tmallOnly": true,
  "sort": "_sale",
  "maxPages": 10
}

Example — Shop Catalog (extended, 60 items/page, price sorting)

{
  "operation": "shopCatalog",
  "userId": "713464357",
  "shopId": "101529349",
  "catalogMode": "extended",
  "sort": "bid",
  "maxPages": 20
}

Example — Product Reviews

{
  "operation": "productReviews",
  "itemId": "742902854135",
  "orderType": "feedbackdate",
  "maxPages": 10
}

Example — Premium Detail (exact final / after-coupon pricing)

{
  "operation": "productDetail",
  "itemId": "744983869996",
  "detailVersion": "v4"
}

Example — Product Q&A (buyer questions & answers)

{
  "operation": "productQuestions",
  "itemId": "742902854135",
  "maxPages": 3
}

💡 How to find IDs

• Item ID — in any Taobao / Tmall product URL after id= https://item.taobao.com/item.htm?id=744983869996 → 744983869996 Every search and shop-catalog row also returns itemId.
• Shop / Seller ID — returned as userId in every keyword-search or detail result row. Chain: run Keyword Search for a brand first, note the top userId, then feed that ID into Shop Catalog.
• Shop ID (for extended catalog) — returned as shopId in product detail and search results. Different from the seller user ID.

---

📤 Output

Each run writes to an Apify dataset with 90+ structured fields per row. Every row carries an _operation discriminator so you can filter mixed datasets.

Core fields (all operations)

Field	Type	Description
_operation	string	Which operation produced this row
recordTime	string	Capture timestamp (ISO-8601) — when the data was actually collected. True capture time on Search, Shop Catalog, Reviews, and every detail version. Use for data-freshness checks.
_fetchedAt	string	ISO-8601 timestamp of when this actor run fetched the row (not the capture time — see recordTime)
itemId	string	Stable product ID
title	string	Full product title
priceYuan	number	Current price in CNY
imageUrl	string	Primary image URL
shopId	string	Seller ID (pivot into Shop Catalog)
shopName	string	Seller display name
status	string	success / error

🔍 Which fields come from which detail version

Each detailVersion returns a different raw field set with different names — and because of automatic fallback the version that answers may not be the one you asked for. This matrix was generated from live payloads for the same products on 2026-08-26, so it reflects what the actor actually emits.

Safe to build on — same name and meaning on every version: itemId, title, shopId, pictUrls, totalStock, soldCount, originalPrice, discountPrice, itemDescHtml and recordTime. Every row also carries the run metadata _operation, _fetchedAt, _page, _sourceItemId and status. (See the fill-rate table under Automatic fallback — v1 and v9 leave some of them empty.)

Field	v3 ⭐ Recommended	v1 🔋 Standard	v9 🆕 Full	v4 💎 Premium
Identity
itemId · title	✓	✓	✓	✓
num_iid · detail_url · cid · rootCatId · crumbs	✓
categoryId · rootCategoryId · seoItemType		✓	✓ (categoryId)
brand · brandId · tmall · location	✓	(location)	(location)
Price
originalPrice · discountPrice (curated)	✓	✓
price · orginal_price · suggestive_price · total_price	✓		(price, range string)
promotionPrice · promotionName · startTime · endTime · remark · hasRangePrice		✓
currency · currencySymbol · exchangePrice · exchangePriceHKD · exchangePriceTWD		✓
mainItemInfo (incl. afterCouponAmountPrice)			✓
itemPrice · DiscountPrice · priceYuan · finalPriceYuan				✓
Stock & sales
totalStock · soldCount (curated, numeric)	✓
num · total_sold · sales	✓		(num, totalCount — rounded text)
sellCount (rounded text, e.g. "1万+")		✓
SKUs / variants
skus (with per-SKU price, orginal_price, quantity)	✓		✓
skuList · skuPVPairList · skuPropertyList		✓
sku2info · skuBase (with finalSkuPriceYuan per variant)				✓
Specs & description
itemDescHtml (curated) · desc	✓	✓	✓
props_list · props_name · property_alias · item_size · item_weight	✓
groupProps (specifications)		✓
attribute · specs · props			✓
Media
pictUrls (curated gallery — populated on all three)	✓	✓	✓
item_imgs · pic_url · prop_imgs · props_imgs · desc_img	✓		(item_imgs)
images · videos · kolVideos		✓
video · videoUrl	✓		✓ (videoUrl)
itemPic				✓
Seller / shop
shopId (curated) · seller_id · nick · seller_info · fans_count · fav_count	✓	(shopId)	(shopId)
shopName · shopUrl · shopIcon · shopCard · taoShopUrl · showShopLinkIcon		✓	(shopName)	(shopName)
creditLevel · evaluates · starts · sellerType · allItemCount · newItemCount · userId		✓	(most)
Logistics / lifecycle
post_fee · express_fee · ems_fee · freight · shipping_to · min_num	✓
delist_time · created_time · modified_time	✓

Totals (fields emitted per row, same products): v3 ≈ 70 · v1 ≈ 52 · v9 ≈ 22 + curated · v4 ≈ 18 (price-focused by design).

⚠️ Why v9 leaves totalStock / soldCount / discountPrice empty. Its stock, sold and price fields are rounded display text — num and totalCount arrive as "1万+" (Chinese for "10,000+") and price as a range like "239.00-269.00". Parsed into the numeric columns, "1万+" becomes 1, which would report a single unit sold for a product that sold ten thousand. They are therefore left empty and passed through as raw text instead of reported wrongly.

⚠️ Why v1 leaves totalStock / soldCount empty. v1 reports sales only as sellCount, the same rounded text ("1万+"), and does not report stock at all. Use v3 Recommended when you need numeric stock or units sold.

ℹ️ v1's promotion block can be stale. promotionPrice is whatever campaign the listing last carried — on a 2026-08-26 sample, 13 of 24 items had a promotion window that had already ended (some three months earlier). Check startTime / endTime before treating discountPrice as the current price, or use v3, whose price is the live listed price.

Keyword Search extras

titleEn (English title), subTitle, discntPriceYuan, commentCount, itemGradeAvg (product rating), sellerLevel, sellerGoodRate, sellerLoc, userType, tags[], _sourceKeyword, _page

Shop Catalog extras

Standard catalog: promotionPrice, finalPromotionPrice, reservePrice, minDiscountPrice, priceAfterCoupon, commissionAmount, commissionRate, payRate30Days, dailySellCount, provcity, levelOneCategoryName, _sourceUserId

Extended catalog: priceFen, priceYuanDouble, priceZKYuanDouble, discntPriceYuan, discntType, commentCount, freeShipping, sellPointMap{}, orderCount30Day, soldCount30Day, _sourceShopId

Product Review extras

The review: reviewId, reviewDate, reviewContent, reviewAppend, reviewAppendDays, reviewRatingStars, reviewTag, reviewPhotos[], reviewVideoUrl, reviewSkuLabel, reviewBuyAmount, reviewUsefulCount

The reviewer: reviewerNick, reviewerAvatar, reviewerVipLevel, reviewerAnonymous, plus _sourceItemId and _page

Example — Product Detail (fresh Full version) row (abridged)

{
  "_operation": "productDetail",
  "recordTime": "2026-06-17T10:43:31.124841598",
  "_fetchedAt": "2026-06-17T10:43:32.486Z",
  "itemId": "744983869996",
  "title": "港版Switch适用多国转换插头 英标转中转换器适用马来西亚",
  "priceYuan": 31.9,
  "priceRange": "31.90-289.00",
  "afterCouponAmountPrice": "31.9",
  "promotionPriceYuan": 31.9,
  "imageUrl": "https://img.alicdn.com/imgextra/i1/713464357/...",
  "imageUrls": ["...", "...", "...", "...", "..."],
  "videoUrl": "https://cloud.video.taobao.com/play/u/713464357/...",
  "skuCount": 8,
  "skus": [
    { "skuId": "6113989610895", "propPath": "1627207:39607078716", "price": 32.9, "originalPrice": 32.9, "quantity": "200" }
  ],
  "shopId": "67095450",
  "shopName": "绿联数码旗舰店",
  "shopUrl": "https://shop67095450.taobao.com",
  "sellerType": "B",
  "userId": "713464357",
  "sellCount": "6000+",
  "attributes": [
    { "key": "品牌", "value": "绿联" },
    { "key": "型号", "value": "S510" }
  ],
  "status": "success"
}

Example — Shop Catalog (extended) row (abridged)

{
  "_operation": "shopCatalog",
  "_catalogVersion": "extended",
  "itemId": "521031921743",
  "title": "绿联适用苹果iPhone14/13/12Promax11plus8充电线mfi认证...",
  "priceYuan": 23.5,
  "originalPriceYuan": 24.87,
  "promotionPriceYuan": 23.5,
  "discountPct": 5.5,
  "imageUrl": "https://img.alicdn.com/i4/713464357/...",
  "commentCount": "4000+",
  "freeShipping": false,
  "sellPoints": ["苹果官方MFi认证", "支持苹果全系快充"],
  "orderCount30Day": "700+",
  "itemUrl": "https://item.taobao.com/item.htm?id=521031921743",
  "status": "success"
}

Example — Keyword Search row (abridged)

{
  "_operation": "keywordSearch",
  "_sourceKeyword": "无线耳机",
  "_page": 1,
  "_fetchedAt": "2026-05-06T08:12:34.000Z",
  "itemId": "675439801234",
  "title": "蓝牙耳机无线5.3降噪入耳式超长续航适用苹果华为小米",
  "titleEn": "Bluetooth Earphones Wireless 5.3 Noise Cancelling",
  "priceYuan": 89.0,
  "discntPriceYuan": 69.0,
  "imageUrl": "https://img.alicdn.com/imgextra/i3/2215.../...",
  "shopId": "428975103",
  "shopName": "数码影音旗舰店",
  "sellerLoc": "广东 深圳",
  "sellerLevel": 15,
  "sellerGoodRate": 98.6,
  "commentCount": "5000+",
  "itemGradeAvg": 4.8,
  "userType": "B",
  "tags": ["蓝牙5.3", "主动降噪", "超长续航"],
  "itemUrl": "https://item.taobao.com/item.htm?id=675439801234",
  "status": "success"
}

Example — Product Review row (abridged)

{
  "_operation": "productReviews",
  "_sourceItemId": "742902854135",
  "_page": 1,
  "_fetchedAt": "2026-05-06T08:20:11.000Z",
  "reviewId": "1234567890",
  "reviewDate": "2026-03-14",
  "reviewContent": "音质很好，降噪效果明显，佩戴也很舒适，续航比想象中长",
  "reviewAppend": "用了一个月了，还是很好用",
  "reviewAppendDays": 28,
  "reviewRatingStars": 5,
  "reviewTag": "5星好评",
  "reviewPhotos": [
    "https://img.alicdn.com/imgextra/i4/.../review1.jpg",
    "https://img.alicdn.com/imgextra/i4/.../review2.jpg"
  ],
  "reviewSkuLabel": "颜色分类: 星空黑",
  "reviewBuyAmount": 1,
  "reviewUsefulCount": 12,
  "reviewerNick": "小***明",
  "reviewerVipLevel": 6,
  "reviewerAnonymous": false,
  "status": "success"
}

Three built-in views

• Overview — all rows, mixed across operations, 18 most-useful columns
• Products — only product rows (search / catalog / detail), hides review-only fields
• Reviews — only review rows, reviewer info + photos + variant purchased

Switch views in the Apify dataset UI — no re-running required.

---

💼 Use Cases & Examples

1. Dropshipping Product Research

Sourcing specialists and dropshipping operators finding hot products with healthy margins.

Input: Keyword Search for a product category (e.g. "wireless earphones", price 100–500 CNY, Tmall only). Output: Ranked list of 100+ products with prices, seller ratings, review counts, shop locations. Use: Sort by itemGradeAvg × commentCount to find validated best-sellers. Chain into Product Detail (full depth) for coupon-adjusted pricing and SKU variant analysis.

2. Competitor Price Monitoring

E-commerce teams tracking competitor prices and promotions across Taobao and Tmall.

Input: Shop Catalog (extended) for each competitor, scheduled daily, sorted by price or comprehensive. Output: 60 products per page with priceZKYuanDouble, discntPriceYuan, and sellPointMap per item. Use: Detect price drops, new promotions, and inventory additions in fewer API calls (60 items/page vs 30). Feed into a BI dashboard with _fetchedAt as the time axis.

3. Private-Label Sourcing

Brand founders identifying white-label manufacturers and OEM partners.

Input: Keyword Search for generic product terms ("unbranded bluetooth speaker"), filter by userType = factory/wholesaler. Output: Sellers with provcity, sellerLevel, sellerGoodRate, dailySellCount indicators. Use: Build a shortlist of credible factories. Deep-dive with Product Detail (full depth) to check SKU variety, attributes, and promotion data for reliability signals.

4. Review Sentiment & Media Mining

Marketing agencies pulling unboxing photos and authentic customer language for ad creative.

Input: Product Reviews for your own or competitor item IDs, sorted by date or relevance. Output: Dataset of review text, photos, videos, ratings, and purchased variants. Use: Extract Chinese review language for UGC ad copy. Download review photos and videos for social proof content. Filter reviewRatingStars + reviewTag to find negative reviews that surface product flaws.

5. Category Intelligence Sweeps

Market researchers mapping an entire product category across Taobao.

Input: Keyword Search with broad queries, maxPages: 50, sorted by sales volume. Output: 500+ products with pricing, seller distribution, category IDs. Use: Build a category map — count sellers per categoryId, compute price quartiles, identify gaps. Export to Tableau or Looker.

6. Brand Catalog Mapping

Amazon sellers doing arbitrage research on Chinese brands expanding overseas.

Input: Keyword Search for the Chinese brand, note top userId + shopId, then Shop Catalog (extended). Output: Complete SKU list with 60 products per page, sell points, and order counts. Use: Map which products the brand sells domestically vs exports. Spot candidates for Amazon FBA. Extended mode's 60 items/page means faster full-catalog dumps.

7. BI & Data Warehouse Enrichment

Data teams augmenting internal product databases with Taobao market data.

Input: Product Detail (full depth) lookups driven by internal item IDs. Output: Canonical Taobao fields with coupon pricing, attributes, and specs joined into your existing product records. Use: Pipe into Snowflake / BigQuery / Postgres. Use _fetchedAt for slowly-changing-dimension logic. Join shopId for seller-level rollups.

---

🔀 Which Chinese E-commerce Scraper Is Right For You?

Your use case	Right tool
🛒 B2C retail product research (consumer prices, SKU variants, authentic reviews)	🎯 This actor — Taobao & Tmall
🏭 B2B wholesale sourcing (find factories, bulk pricing, MOQ, Gold Supplier data)	1688 Wholesale Scraper · Alibaba Supplier Scraper
🌍 Cross-border retail for Western buyers (English listings, shipping-ready)	AliExpress Product Scraper
♻️ Second-hand / used goods	Xianyu (Goofish) Listings Scraper
💼 Dropshipping research needing retail prices + SKU variants + Chinese customer reviews	🎯 This actor — Taobao & Tmall

Why Taobao & Tmall specifically

• Taobao = China's #1 consumer marketplace — the equivalent of US Amazon for retail. Lower prices, SKU-level variants, authentic customer reviews with photos + videos.
• Tmall = Taobao's premium brand-store tier — the equivalent of Amazon Brand Registry. Use the tmallOnly filter when you need licensed sellers or official stores only.
• Alibaba and 1688 = B2B wholesale. Different audience (importers, resellers). Products listed in bulk MOQ, usually unbranded.
• AliExpress = Alibaba's retail export site. English-first, but a subset of Taobao inventory sold at export prices with slower shipping. Scraping Taobao directly gets you the domestic listing price.

This actor is built for Taobao and Tmall retail data specifically, and it bundles product detail, keyword search, shop catalog, reviews and buyer Q&A into one place.

---

🔗 Integration Examples

JavaScript / Node.js

import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: 'YOUR_TOKEN' });

const run = await client.actor('sian.agency/taobao-tmall-product-scraper').call({
  operation: 'keywordSearch',
  keyword: 'iphone 15',
  tmallOnly: true,
  sort: '_sale',
  maxPages: 5,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(`Found ${items.length} products`);
items.forEach(p => console.log(`${p.title} — ¥${p.priceYuan} (${p.shopName})`));

Python

from apify_client import ApifyClient

client = ApifyClient('YOUR_TOKEN')

run = client.actor('sian.agency/taobao-tmall-product-scraper').call(
    run_input={
        'operation': 'shopCatalog',
        'userId': '713464357',
        'shopId': '101529349',
        'catalogVersion': 'extended',
        'sort': 'coefp',
        'maxPages': 10,
    }
)

for item in client.dataset(run['defaultDatasetId']).iterate_items():
    print(item['itemId'], item['title'], item.get('priceYuan'))

cURL

curl -X POST "https://api.apify.com/v2/acts/sian.agency~taobao-tmall-product-scraper/runs?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "productDetail",
    "itemId": "744983869996",
    "detailVersion": "v1"
  }'

Automation Workflows (n8n / Zapier / Make)

1. Trigger: Schedule (daily/hourly) or webhook on a product tracker
2. Apify Run: Call this actor with your chosen operation and inputs
3. Process: Parse the returned dataset — filter by _operation, pick the view you need
4. Action: Save to Google Sheets / Airtable / Postgres, alert on price drops, generate reports

---

📊 Performance & Pricing

🎁 FREE Tier (Try It Now)

• 5 items per run — full feature access across all five operations
• No credit card required
• Perfect for evaluating the output shape before scaling up

💎 PAID Tier (Production Ready)

• Unlimited items per run — pull hundreds of products or thousands of reviews in a single run
• Pay-per-result: you're only charged for successful rows
• Three dataset views unlocked by default for BI integration

💰 Flat pay-per-result pricing — no monthly minimums, no hidden fees.

🔗 View current pricing

---

❓ Frequently Asked Questions

Q: How many products / reviews can I scrape in one run? A: FREE tier: 5 per run. PAID tier: unlimited, capped only by maxPages (up to 50). A single Keyword Search run with maxPages: 50 returns up to 500 products; a single Shop Catalog (extended) run can return 3,000+ (60 items/page × 50 pages).

Q: Do I need a Taobao account or any API key? A: No. No account, no API key, no setup. Paste an item ID or keyword and run.

Q: What output formats are available? A: JSON, CSV, Excel, XML, HTML — exported directly from the Apify dataset UI or API.

Q: What's the difference between product detail depth levels? A: standard = full rich payload (SKUs, Q&A, coupons). lite = compact fast response. full = flat response with coupon-adjusted pricing (afterCouponAmountPrice), full attributes, specs, and promotion data. For most use cases, full gives the best balance of completeness and speed.

Q: When should I use the extended shop catalog instead of standard? A: Use extended when you need: (1) 60 items per page instead of 30 (fewer API calls for large catalogs), (2) price or new-arrivals sorting, or (3) sell-point highlights per product. Extended mode requires both userId and shopId (find shopId from any product detail or search result).

Q: Does it work with Taobao Mobile / Xianyu / 1688? A: This actor targets Taobao and Tmall. For 1688 and Xianyu, check our SIÁN Agency Store for dedicated actors.

Q: How fresh is the data? A: It depends on the operation and, for Product Detail, on the version you pick:

• Keyword Search, Shop Catalog, Reviews, and every live Product Detail version (Recommended / Standard / Full) are collected live at request time. Every row carries a recordTime field = the exact capture timestamp — use it as a freshness proof in downstream pipelines.

_fetchedAt records when the actor ran; recordTime records when the data was actually captured — prefer recordTime for freshness checks.

Q: Can I get English translations? A: Search results include a machine-translated titleEn field where available. Product titles, descriptions, and reviews are returned in their original Chinese — pair with a translation step downstream for full English output.

Q: Is it legal to scrape Taobao? A: Yes — this actor only accesses publicly available product and seller data. See the Legal section below.

Q: How long does a run take? A: Product Detail: ~2 seconds per item. Keyword Search: ~2 seconds per page (10 items). Shop Catalog (standard): ~3 seconds per page (30 items). Shop Catalog (extended): ~5 seconds per page (60 items). Product Reviews: ~3 seconds per page (20 reviews).

---

🐛 Troubleshooting

Empty dataset for Keyword Search

• The query may be too narrow — try a broader term or remove price filters.
• Set tmallOnly: false to include Taobao C2C sellers.

status: error with "item not found"

• The itemId has been delisted or never existed. Verify by opening https://item.taobao.com/item.htm?id=<itemId> in a browser.

Shop Catalog (extended) returns "Server error"

• Confirm you're providing both userId and shopId — extended mode requires both. Find shopId from a Product Detail or Keyword Search result.
• The sort value must be one of: coefp, hotsell, oldstarts, bid, _bid (not _sale or _default).

Shop Catalog returns fewer items than expected

• Standard mode returns ~30 items/page, extended returns 60. The actor stops early when no more pages are available.
• Confirm the userId is the seller ID, not a product ID. It's the number you see as userId in search results.

Fields are null for a product I know exists

• Some fields (e.g. brandName, categoryName) are only populated for certain product categories or by Tmall brand stores.
• totalStock and soldCount are only filled by v3 Recommended (the default). If you pinned detailVersion to v1 or v9, switch back to v3.
• Try switching detailVersion to v1 (Standard) for the deepest pricing/spec blocks, or v9 Full for a flat cross-check — coverage differs per product.

---

⚖️ Is it legal to scrape data?

Our actors are ethical and do not extract any private user data, such as email addresses, gender, or location. They only extract what the user has chosen to share publicly. We therefore believe that our actors, when used for ethical purposes by Apify users, are safe.

However, you should be aware that your results could contain personal data (for example, reviewer nicknames or avatar URLs). Personal data is protected by the GDPR in the European Union and by other regulations around the world. You should not scrape personal data unless you have a legitimate reason to do so. If you're unsure whether your reason is legitimate, consult your lawyers.

You can also read Apify's blog post on the legality of web scraping.

---

🤝 Support

Join our active support community

• For issues or feature requests, open an issue in the actor's repository
• Check SIÁN Agency Store for more automation tools — Instagram, TikTok, LinkedIn, YouTube scrapers and more
• 📧 apify@sian-agency.online

---

Built by SIÁN Agency | More Tools