Technical Deep Dive: Taobao Item Details API - Full Guide & Standard JSON Reference
Introduction
As one of the world’s largest and most complex e-commerce ecosystems, Taobao (operated by Alibaba) powers millions of merchant operations, third-party ERP systems, and cross-platform data synchronization workflows. The taobao.item.get API, part of the Taobao Open Platform (TOP), serves as the core technical gateway for developers to access structured, real-time product data directly from the platform. Unlike generic public web scraping solutions, this official RESTful interface guarantees data accuracy, stability, and compliance with Alibaba’s developer rules, making it the industry-standard choice for production-level e-commerce integration.
This guide breaks down the full technical architecture, mandatory request parameters, and provides a production-grade standard JSON response reference to help developers quickly build stable Taobao data integration pipelines.
1. Core Interface Basic Information
The taobao.item.get interface is a production-grade RESTful service hosted on Alibaba’s global open platform gateway.
Item | Specification |
Official API Name | taobao.item.get (Get Item Full Details) |
Communication Protocol | HTTPS POST (Recommended) / GET |
Default Data Format | JSON (XML is also supported for legacy systems) |
Official Gateway Endpoint | https://eco.taobao.com/router/rest |
Authentication Mechanism | AppKey + AppSecret + OAuth 2.0 SessionKey + HMAC-SHA256 Signature |
Typical Use Cases | Product data synchronization, real-time price monitoring, inventory validation, third-party storefront reconstruction, product research and selection |
2. Full Request Parameter Breakdown
Calling this API strictly follows Taobao Open Platform’s TOP signature specification. All non-empty parameters must be sorted lexicographically and encrypted with the AppSecret to generate a valid signature value.
2.1 Mandatory Public Gateway Parameters
These parameters are required for every TOP API call, used for platform authentication and request tracing:
Parameter Name | Type | Required | Description |
app_key | String | Yes | Unique application identifier, obtained after creating your developer account on Taobao Open Platform |
method | String | Yes | Fixed as taobao.item.get to specify the target interface |
session | String | Yes | OAuth 2.0 authorized SessionKey, represents the permission scope of the current requester |
timestamp | String | Yes | East 8 timezone timestamp, formatted as yyyy-MM-dd HH:mm:ss, prevents replay attacks |
v | String | Yes | API protocol version, the stable version is 2.0 |
sign_method | String | Yes | Signature algorithm, hmac-sha256 is strongly recommended for security |
sign | String | Yes | Final encrypted signature value generated by AppSecret |
format | String | No | Response data format, default value is json |
2.2 Business Core Parameters
These parameters control the actual product data returned by the interface:
Parameter Name | Type | Required | Description |
num_iid | Long | Yes | Taobao product digital ID, extracted directly from the product detail page URL |
fields | String | Yes | Custom return field list, for example num_iid,title,price,sku. Explicitly specifying required fields can significantly reduce response latency |
3. Standard Production JSON Response Reference
Below is a standard full JSON response that strictly follows Taobao’s official interface return specification. This structure includes all high-value business fields for e-commerce development, and can be directly used for debugging and system docking:
Use the website: o0b.cn/anzexi
{
"taobao_item_get_response": {
"code": 0,
"msg": "success",
"request_id": "tb_req_20260917094522107",
"item": {
"num_iid": 1003783113480,
"title": "Apple iPhone 16 Pro 256GB Titanium 5G Dual SIM Smartphone",
"nick": "Apple Tmall Official Flagship Store",
"cid": 50012079,
"outer_id": "APPLE-IP16PRO-256-TI",
"approve_status": "onsale",
"total_stock": 12600,
"current_price": "8999.00",
"list_time": "2026-09-10 10:00:00",
"delist_time": "",
"detail_description": "<p>New titanium design, A18 Pro chip, leading performance experience...</p>",
"main_pic_url": "https://gd-hbimg.alicdn.com/imgextra/i1/O1CN01kLqZ7L1zqKzqKzqKz_!!6000000007239-2-tps-800-800.jpg",
"is_tmall_official": true,
"sku_list": {
"sku": [
{
"sku_id": 4567890123456,
"property_path": "1627207:28349;1627209:28351",
"property_display": "Color: Natural Titanium; Storage: 256GB",
"sku_price": "8999.00",
"custom_outer_id": "SKU-001",
"sku_stock": 3200
},
{
"sku_id": 4567890123457,
"property_path": "1627207:28350;1627209:28351",
"property_display": "Color: White Titanium; Storage: 256GB",
"sku_price": "8999.00",
"custom_outer_id": "SKU-002",
"sku_stock": 2800
}
]
},
"delivery_info": {
"post_fee": "0.00",
"express_fee": "0.00",
"free_shipping_threshold": 0
},
"media_resources": {
"product_images": [
"https://img.alicdn.com/imgextra/i1/1.jpg",
"https://img.alicdn.com/imgextra/i2/2.jpg",
"https://img.alicdn.com/imgextra/i3/3.jpg"
],
"promo_video_url": "https://cloud.video.taobao.com/play/u/123456/p/1/e/6/t/1/987654321.mp4"
}
}
}
}