Taobao APIitem.taobao.com ↗
Retrieve price, images, seller location, and weight from any Taobao product listing by item ID. Covers CNY pricing, promotional prices, and product photos.
What is the Taobao API?
The Taobao Product Detail API exposes 8 data fields from item.taobao.com listings through a single get_product_detail endpoint. Pass any numeric Taobao item ID to get the current price, original price, promotional price, first product image URL, seller location, currency (always CNY), title, and weight where available. It targets the public world.taobao.com endpoint, so no Taobao account credentials are required from the caller.
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 by item ID."""
from parse_apis.item_taobao_com_api import Taobao, ProductNotFound
client = Taobao()
# Fetch a product by its numeric item ID
product = client.products.get(item_id="948892581504")
print(f"Title: {product.title}")
print(f"Price: {product.price} {product.currency}")
print(f"Image: {product.first_image_url}")
print(f"Weight: {product.weight}")
print(f"Location: {product.location}")
# 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 / ProductNotFound")
Retrieve product price, first main photo URL, and weight from a Taobao product listing. Uses the public world.taobao.com endpoint which provides pricing, images, seller info, and ratings without authentication. Weight/specifications data is not available through the public endpoint and returns null. The promotion price is returned when available; otherwise the original price is used.
| 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",
"weight": "string or null, product weight from specifications (null when not available publicly)",
"item_id": "string",
"currency": "string, always CNY",
"location": "string, seller location",
"original_price": "string representing the original listed price",
"first_image_url": "string URL of the first product photo",
"promotion_price": "string representing promotional price if active, otherwise same as original"
},
"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 returns
The get_product_detail endpoint accepts one required parameter — item_id, a numeric string found in the id= query parameter of any Taobao product URL (e.g. 948892581504). The response includes price, original_price, and promotion_price in CNY, letting you distinguish between the standard listed price and any active markdown. first_image_url returns the URL of the lead product photo. location gives the seller's city or province, and title returns the full listing title.
Weight and specifications
The weight field is returned as a string when the specification is publicly available for a given listing, and null when it is not. Weight availability depends on what the seller has declared in the product specs; it is not guaranteed for every item. No other specification fields (dimensions, material, etc.) are currently returned.
Coverage and freshness
The endpoint covers any publicly accessible Taobao listing. Items that require a logged-in session to view — such as some cross-border or restricted listings — may not return complete data. currency is always CNY; no currency conversion is performed. The API returns current data for the requested item ID at call time; there is no built-in historical pricing or batch lookup across multiple IDs in a single request.
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?+
- Track price drops on specific Taobao listings by polling
priceandpromotion_priceover time - Build a price comparison tool that displays
original_pricealongsidepromotion_pricefor Chinese market goods - Populate a product catalog with Taobao titles and
first_image_urlfor display in a third-party storefront - Identify seller geography using the
locationfield to filter or prioritize suppliers by region - Cross-reference
weightdata from Taobao specs when calculating shipping cost estimates - Validate that a Taobao item ID is still active and publicly available before processing an order
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Taobao have an official developer API?+
What is the difference between `price`, `original_price`, and `promotion_price` in the response?+
original_price is the price as listed by the seller before any active promotion. promotion_price reflects the discounted price when a promotion is running; when no promotion is active it matches original_price. price is the current effective price shown on the listing page.Is weight data reliably returned for all items?+
weight field returns null when the seller has not declared weight in the product's public specification sheet, or when weight is not exposed through the public endpoint used. Sellers on Taobao are not required to fill in all specification fields, so null responses are common for certain product categories.Can I retrieve seller ratings, reviews, or sales volume for a listing?+
price, original_price, promotion_price, title, first_image_url, location, currency, and weight. Seller ratings, review counts, and sales figures are not included in the response. You can fork this API on Parse and revise it to add an endpoint that covers those fields.Can I look up multiple Taobao item IDs in a single request?+
get_product_detail accepts one item_id per call. For multiple products you would need to make separate requests. You can fork this API on Parse and revise it to add a batch lookup endpoint that accepts a list of item IDs.