Taobao APIitem.taobao.com ↗
Fetch Taobao product details, images, variants, and descriptions by item ID. 4 endpoints covering price, SKUs, reviews, and seller info in CNY.
What is the Taobao API?
The Taobao Item API provides 4 endpoints for extracting structured product data from item.taobao.com listings using a numeric item ID. The get_product_detail endpoint returns up to 15 fields per listing including price in CNY, main carousel images, seller location, average rating, review count, and SKU variant objects. The remaining endpoints narrow scope to images, description content, or variant data independently.
curl -X GET 'https://api.parse.bot/scraper/c09240ce-ae43-41b7-91ba-a8a2c7d2cb80/get_product_detail?item_id=948892581504' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace item-taobao-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Taobao Product API — fetch product details, images, content, and variants."""
from parse_apis.Taobao_Product_API import Taobao, ProductNotFound
client = Taobao()
# Fetch full product details by item ID
product = client.products.get(item_id="948892581504")
print(f"Title: {product.title}")
print(f"Price: {product.price} {product.currency}")
print(f"Seller: {product.seller_name} (ID: {product.seller_id})")
# Access nested review summary data
print(f"Rating: {product.reviews.average_rating}, Reviews: {product.reviews.review_count}")
for review in product.reviews.reviews[:3]:
print(f" {review.reviewer_name}: {review.comment} (sku: {review.sku_info})")
# Access description content directly from product
print(f"Description: {product.description_text[:80]}")
# Get full product gallery via the instance method
gallery = product.gallery()
print(f"Gallery has {gallery.image_count} image(s)")
# Get product description content
content = product.content()
print(f"Content images: {content.description_image_count}")
# Get SKU variant data
variants_data = product.sku_variants()
print(f"Variants found: {variants_data.variants_count}")
for v in variants_data.variants[:3]:
props = ", ".join(f"{p.name}={p.value}" for p in v.properties)
print(f" SKU {v.sku_id}: {props} price={v.price}")
# Handle a non-existent product gracefully
try:
missing = client.products.get(item_id="999999999999")
print(missing.title)
except ProductNotFound as exc:
print(f"Product not found: {exc.item_id}")
print("exercised: products.get / product.gallery / product.content / product.sku_variants / ProductNotFound")
Retrieve comprehensive product details from a Taobao product listing including pricing, images, variants, specifications, reviews, seller info, and description content. Uses the public world.taobao.com endpoint. Variants and specifications require authentication and return empty when accessed publicly. Reviews include the review_count (total) and average_rating derived from the good-review percentage, plus a limited preview of individual reviews (typically 1) from the public SSR response; full review pagination requires authentication. Description includes meta-level product copy and gallery images. Seller info includes seller_id, seller_name, and shop_name.
| Param | Type | Description |
|---|---|---|
| item_idrequired | string | Numeric Taobao item ID (e.g. 948892581504). Found in the id= parameter of Taobao product URLs. |
{
"type": "object",
"fields": {
"price": "string representing the current price in CNY",
"title": "string, product name/title",
"images": "array of all main carousel image URLs",
"weight": "string or null, product weight from specifications (e.g. '0.3kg'); null when not available publicly",
"item_id": "string, the numeric item ID",
"reviews": "object with average_rating (float), review_count (integer), and reviews array (limited preview from public endpoint, typically 1 review)",
"currency": "string, always CNY",
"location": "string, seller location",
"variants": "array of SKU variant objects (empty when auth required); each has sku_id, properties, price, original_price, stock, sku_image_url",
"seller_id": "string, numeric seller/user ID",
"shop_name": "string or null, shop display name",
"description": "object with description_text (string) and description_images (array of image URLs)",
"image_count": "integer, number of main carousel images",
"seller_name": "string or null, seller shop name",
"original_price": "string representing the original listed price",
"specifications": "object of specification key-value pairs (empty when auth required)",
"first_image_url": "string URL of the first product photo",
"promotion_price": "string representing promotional price if active, otherwise same as original",
"description_text": "string, SEO/meta description summarizing product reviews and key attributes",
"description_images": "array of image URLs from the product description/detail section",
"description_image_count": "integer, number of description images"
},
"sample": {
"data": {
"price": "59.00",
"title": "馬家夏季新款速乾男士...",
"weight": null,
"item_id": "948892581504",
"currency": "CNY",
"location": "安徽合肥",
"original_price": "59.00",
"first_image_url": "https://img.alicdn.com/imgextra/i1/672197680/O1CN01omIqdY26bUr7vgJeI_!!672197680.jpg",
"promotion_price": "59.00"
},
"status": "success"
}
}About the Taobao API
What the API Covers
All four endpoints accept a single required input — item_id, the numeric ID found in the id= query parameter of any Taobao product URL. get_product_detail returns the widest response shape: price, title, images, weight, currency (always CNY), location, seller_id, a reviews object containing average_rating, review_count, and a reviews array, and a variants array of SKU objects.
Endpoint Breakdown
get_product_images returns title, images, item_id, and image_count — useful when you only need the product gallery without triggering a full detail fetch. get_product_content returns title, description_text (a meta/SEO summary incorporating review highlights and key attributes), description_images, and description_image_count. get_product_variants focuses entirely on SKU data: each variant object in the variants array carries sku_id, properties, price, original_price, stock, and sku_image_url, and the endpoint tries multiple data locations in the listing before falling back to review-derived variant inference.
Known Limitations
The variants array in get_product_detail returns empty for listings that require authenticated sessions to expose full SKU data; use get_product_variants in those cases, as it applies additional extraction strategies. The weight field is null when the listing does not surface that specification publicly. All prices are denominated in CNY — there is no currency conversion layer in the response.
Official API
Taobao's parent company Alibaba operates the Taobao Open Platform (open.taobao.com), which provides an official API for sellers and ISVs. It requires application approval and is oriented toward Taobao ecosystem partners rather than general product data retrieval.
The Taobao API is a managed, monitored endpoint for item.taobao.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when item.taobao.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official item.taobao.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Sync Taobao product prices and CNY amounts into a cross-border price comparison tool
- Build a product image dataset by collecting carousel images across many item IDs via get_product_images
- Extract SKU variant matrices including stock levels and per-variant prices using get_product_variants
- Aggregate seller location data from get_product_detail to analyze regional supply patterns
- Pull description_text from get_product_content to feed into translation or NLP pipelines
- Monitor average_rating and review_count changes over time for competitive product tracking
- Retrieve product weight specifications for logistics cost estimation in cross-border shipping tools
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.