Taobao and Tmall Product Details API (V1)
Retrieves Taobao or Tmall product details by item ID through the V1 endpoint. Use it to perform direct product lookup for catalog research, product monitoring, or ecommerce analysis.
Highlights
Condition · Price
Returns the original product price. SKU prices are available for some products and may be absent for others.
Capability · Attributes
Provides a grouped product-parameter table.
Capability · SKU options
Provides SKU identifiers, specification options and quantity information.
Capability · Main and carousel images
Provides product main and carousel images.
Condition · Description images
Description images are included in description HTML and need to be extracted; a separate image list is not provided.
Condition
Some products may not be available through this endpoint.
Parameters
| Name | In | Type | Required | Default | Description |
|---|---|---|---|---|---|
token | query | string | Yes | - | Access token for this API service. |
itemId | query | string | Yes | - | Unique product identifier on Taobao/Tmall (item ID). |
Code Samples
curl --max-time 120 -X GET 'https://api.justoneapi.com/api/taobao/get-item-detail/v1?token=YOUR_API_KEY&itemId=VALUE'I want to use the "Product Details (V1)" API from JustOneAPI.
Base URL: https://api.justoneapi.com.
API Path: /api/taobao/get-item-detail/v1?token=YOUR_API_KEY&itemId=VALUE
API Endpoint: BASE_URL + /api/taobao/get-item-detail/v1?token=YOUR_API_KEY&itemId=VALUE
HTTP Method: GET
Authentication: Append the "token" query parameter to the URL.
OpenAPI Definition: https://docs.justoneapi.com/openapi/taobao-and-tmall/product-details-v1-en.json
Parameters:
- token (query): Access token for this API service. (Required)
- itemId (query): Unique product identifier on Taobao/Tmall (item ID). (Required)
Return format: safely handle JSON or text according to the actual Content-Type.
Response Handling & Error Codes:
1. Business results should be determined by the "code" field in the response body (code 0 means success).
2. Timeout Recommendation: Set the request timeout to 120 seconds. If 120 seconds is too long for your use case, use at least 60 seconds, but a small number of requests may time out before receiving a result.
3. Business Code Reference:
- 0: Success
- 100: Invalid or Inactive Token
- 301: Collection Failed. Please Retry.
- 302: Rate Limit Exceeded
- 303: Daily Quota Exceeded
- 400: Invalid Parameters
- 500: Internal Server Error
- 600: Permission Denied
- 601: Insufficient Balance
- 602: Token Budget Exceeded
4. Code 601 means the shared account balance is insufficient. Code 602 means the current API token's own cumulative budget limit has been reached. Token budget limits do not transfer funds out of the shared account balance.
Please help me write a script in my preferred programming language to call this API and handle the response.import requests
BASE_URL = "https://api.justoneapi.com" # Provided by OpenAPI servers
url = BASE_URL + "/api/taobao/get-item-detail/v1?token=YOUR_API_KEY&itemId=VALUE"
response = requests.get(url, timeout=120)
print(response.status_code)
if response.content:
content_type = response.headers.get("content-type", "").lower()
if "json" in content_type:
try:
print(response.json())
except ValueError:
print(response.text)
elif content_type.startswith("text/") or "xml" in content_type or content_type.split(";", 1)[0].strip() in {"application/javascript", "application/x-www-form-urlencoded", "application/graphql"}:
print(response.text)
else:
with open("response.bin", "wb") as output:
output.write(response.content)
print(f"Saved {len(response.content)} bytes to response.bin")const BASE_URL = "https://api.justoneapi.com"; // Provided by OpenAPI servers
const url = BASE_URL + "/api/taobao/get-item-detail/v1?token=YOUR_API_KEY&itemId=VALUE";
const response = await fetch(url, {
method: "GET",
signal: AbortSignal.timeout(120000)
});
console.log(response.status);
const responseBytes = await response.arrayBuffer();
if (responseBytes.byteLength) {
const contentType = (response.headers.get("content-type") || "").toLowerCase();
const mediaType = contentType.split(";", 1)[0].trim();
const textual = contentType.startsWith("text/") || contentType.includes("json") || contentType.includes("xml") || ["application/javascript", "application/x-www-form-urlencoded", "application/graphql"].includes(mediaType);
if (textual) {
const responseText = new TextDecoder().decode(responseBytes);
let data = responseText;
if (contentType.includes("json")) {
try { data = JSON.parse(responseText); } catch { /* Keep the raw body. */ }
}
console.log(data);
} else {
console.log(`Received ${responseBytes.byteLength} binary bytes`);
}
}import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
public class Main {
public static void main(String[] args) throws Exception {
final String BASE_URL = "https://api.justoneapi.com"; // Provided by OpenAPI servers
final String url = BASE_URL + "/api/taobao/get-item-detail/v1?token=YOUR_API_KEY&itemId=VALUE";
HttpClient client = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(120)).build();
HttpRequest.Builder builder = HttpRequest.newBuilder()
.uri(URI.create(url))
.timeout(Duration.ofSeconds(120))
.method("GET", HttpRequest.BodyPublishers.noBody());
HttpRequest request = builder.build();
HttpResponse<byte[]> response = client.send(request, HttpResponse.BodyHandlers.ofByteArray());
System.out.println(response.statusCode());
String contentType = response.headers().firstValue("content-type").orElse("").toLowerCase();
String mediaType = contentType.split(";", 2)[0].trim();
if (contentType.startsWith("text/") || contentType.contains("json") || contentType.contains("xml") || mediaType.equals("application/javascript") || mediaType.equals("application/x-www-form-urlencoded") || mediaType.equals("application/graphql")) {
System.out.println(new String(response.body(), StandardCharsets.UTF_8));
} else {
Files.write(Path.of("response.bin"), response.body());
System.out.println("Saved " + response.body().length + " bytes to response.bin");
}
}
}package main
import (
"fmt"
"io"
"os"
"strings"
"net/http"
"time"
)
const BASE_URL = "https://api.justoneapi.com" // Provided by OpenAPI servers
func main() {
client := &http.Client{Timeout: 120 * time.Second}
url := BASE_URL + "/api/taobao/get-item-detail/v1?token=YOUR_API_KEY&itemId=VALUE"
req, _ := http.NewRequest("GET", url, nil)
resp, _ := client.Do(req)
defer resp.Body.Close()
fmt.Println(resp.StatusCode)
bodyBytes, _ := io.ReadAll(resp.Body)
contentType := strings.ToLower(resp.Header.Get("Content-Type"))
mediaType := strings.TrimSpace(strings.SplitN(contentType, ";", 2)[0])
if strings.HasPrefix(contentType, "text/") || strings.Contains(contentType, "json") || strings.Contains(contentType, "xml") || mediaType == "application/javascript" || mediaType == "application/x-www-form-urlencoded" || mediaType == "application/graphql" {
fmt.Println(string(bodyBytes))
} else {
os.WriteFile("response.bin", bodyBytes, 0600)
fmt.Printf("Saved %d bytes to response.bin\n", len(bodyBytes))
}
}<?php
$BASE_URL = 'https://api.justoneapi.com'; // Provided by OpenAPI servers
$url = $BASE_URL . '/api/taobao/get-item-detail/v1?token=YOUR_API_KEY&itemId=VALUE';
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 120);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
$contentType = strtolower((string) curl_getinfo($ch, CURLINFO_CONTENT_TYPE));
curl_close($ch);
echo $status . PHP_EOL;
$mediaType = trim(explode(';', $contentType, 2)[0]);
if (str_starts_with($contentType, 'text/') || str_contains($contentType, 'json') || str_contains($contentType, 'xml') || in_array($mediaType, ['application/javascript', 'application/x-www-form-urlencoded', 'application/graphql'], true)) {
echo $response;
} else {
file_put_contents('response.bin', $response);
echo 'Saved ' . strlen($response) . ' bytes to response.bin' . PHP_EOL;
}Response Fields
Key fields in a successful response (code = 0).
Product information14 fields
data
Taobao or Tmall product detail with listing information, prices, specifications, and related content as available.
| Field | Type | Description |
|---|---|---|
item | object | Product information for the requested item. |
item.itemId | integer | Taobao or Tmall item ID, returned as an integer. |
item.title | string | Display title of the listing. |
item.categoryId | string | Category ID assigned to the item, returned as text. |
item.rootCategoryId | string | Top-level category ID assigned to the item, returned as text. |
item.location | string | Location displayed for the item. |
item.sellCount | string | Sales count text displayed for the item. |
item.seoItemType | string | Platform listing type label returned for the item. |
itemDesc | string | Product description as HTML text. Description image links can appear inside the markup. |
itemExist | boolean | Item existence flag reported in the product detail. |
success | boolean | Success flag reported inside the product detail data. |
areaLimit | boolean | Whether a regional restriction is reported for the item. |
freeShipping | boolean | Whether the item is marked as offering free shipping. |
skuId | integer | SKU ID returned alongside the product information. |
Images and videos21 fields
data.item
| Field | Type | Description |
|---|---|---|
images | array | Product image URLs in the order returned. |
images[] | string | URL of a product image. |
videos | array | Videos returned with the listing. |
videos[] | object | One product video. |
videos[].videoUrl | string | URL for the product video. |
videos[].coverUrl | string | Cover image URL for the product video. |
videos[].uploadDate | string | Upload date text reported for the product video. |
kolVideos | array | Creator videos associated with the listing, when returned. |
kolVideos[] | object | One video from a creator associated with the listing. |
kolVideos[].nick | string | Display nickname of the creator. |
kolVideos[].coverUrl | string | Cover image URL for the creator video. |
kolVideos[].video5sUrl | string | URL provided for the short video preview. |
kolVideos[].videoUrl | string | URL for the creator video. |
beehiveContent | object | Related content shown with the product. |
beehiveContent.accountName | string | Display name of the related content account. |
beehiveContent.contentAggreName | string | Display name of the related content collection. |
beehiveContent.contentAggreUrl | string | Link to the related content collection, when available. |
beehiveContent.contentCover | string | Cover image URL for the related content. |
beehiveContent.contentDetailUrl | string | Link to the related content details. |
beehiveContent.contentSummary | string | Summary text for the related content. |
beehiveContent.contentTitle | string | Display title of the related content. |
Prices and coupons22 fields
data
| Field | Type | Description |
|---|---|---|
creativeText | string | Promotional display text associated with the item, when available. |
itemPrice | object | Item-level pricing and promotion display information. |
itemPrice.price | string | Item price text returned for the listing, when available. |
itemPrice.originalPrice | string | Reported original item price as text. |
itemPrice.promotionPrice | string | Reported item promotional price as text. |
itemPrice.promotionName | string | Display name of the item promotion. |
itemPrice.hasRangePrice | boolean | Whether the price information is marked as a range. |
itemPrice.exchangePriceHKD | string | Displayed price converted to Hong Kong dollars. |
itemPrice.exchangePriceTWD | string | Displayed price converted to New Taiwan dollars. |
itemPrice.startTime | string | Reported start time text for the price information. |
itemPrice.endTime | string | Reported end time text for the price information. |
itemPrice.remark | string | Display note provided with the price information. |
coupon | object | Coupon information returned for the item. |
coupon.coupon | object | Coupon details embedded in the response. |
coupon.coupon.couponClickUrl | string | Link provided for the coupon, when available. |
coupon.coupon.couponInfo | string | Displayed coupon description. |
coupon.coupon.couponPrice | integer | Reported coupon amount as an integer value. |
coupon.coupon.couponStartTime | string | Reported start time text for the coupon. |
coupon.coupon.couponEndTime | string | Reported end time text for the coupon. |
coupon.coupon.couponRemainCount | integer | Reported number of coupons remaining. |
coupon.coupon.couponTotalCount | integer | Reported total number of coupons. |
coupon.coupon.itemUrl | string | Item listing link provided with the coupon information. |
SKUs and quantity21 fields
data
| Field | Type | Description |
|---|---|---|
itemSkuDO | object | SKU details, specification combinations, and selectable options. |
itemSkuDO.skuList | object | SKU map whose keys are SKU IDs represented as strings. Pricing fields can be absent for some items. |
itemSkuDO.skuList.{key} | object | Details of the SKU identified by the map key. |
itemSkuDO.skuList.{key}.skuId | integer | SKU ID, returned as an integer. |
itemSkuDO.skuList.{key}.propPath | string | SKU specification path. Each pair joins a property ID and value ID with a colon, and multiple pairs are separated by semicolons. |
itemSkuDO.skuList.{key}.quantity | string | Reported quantity for this SKU, returned as text. |
itemSkuDO.skuList.{key}.price | string | Reported price text for this SKU, when available. |
itemSkuDO.skuList.{key}.priceMoney | integer | Reported integer representation of this SKU price, when available. |
itemSkuDO.skuPVPairList | array | List of SKU IDs and their specification paths. |
itemSkuDO.skuPVPairList[] | object | One SKU and its selected specification combination. |
itemSkuDO.skuPVPairList[].skuId | integer | SKU ID, returned as an integer. |
itemSkuDO.skuPVPairList[].propPath | string | SKU specification path. Each pair joins a property ID and value ID with a colon, and multiple pairs are separated by semicolons. |
itemSkuDO.skuPropertyList | array | Specification properties that define the item variants. |
itemSkuDO.skuPropertyList[] | object | One specification property and its options. |
itemSkuDO.skuPropertyList[].pid | integer | Specification property ID, returned as an integer. |
itemSkuDO.skuPropertyList[].name | string | Display name of the specification property. |
itemSkuDO.skuPropertyList[].propertyValues | array | Selectable values for the specification property. |
itemSkuDO.skuPropertyList[].propertyValues[] | object | One option value for the specification property. |
itemSkuDO.skuPropertyList[].propertyValues[].vid | integer | Option value ID, returned as an integer. |
itemSkuDO.skuPropertyList[].propertyValues[].name | string | Display name of the option value. |
itemSkuDO.skuPropertyList[].propertyValues[].image | string | Image URL for the option value, when available. |
Product attributes6 fields
data
| Field | Type | Description |
|---|---|---|
props | object | Grouped product attributes displayed for the item. |
props.groupProps | array | Attribute groups with platform-provided group and attribute names. |
props.groupProps[] | object | An object keyed by attribute group name. |
props.groupProps[].{key} | array | List of attributes for the group identified by the map key. |
props.groupProps[].{key}[] | object | An object keyed by the displayed attribute name. |
props.groupProps[].{key}[].{key} | string | Displayed text value of the attribute named by the key. |
Shop and trade28 fields
data
| Field | Type | Description |
|---|---|---|
seller | object | Shop and seller information returned with the item. |
seller.shopId | integer | Marketplace shop ID, returned as an integer. |
seller.userId | integer | Marketplace account ID of the seller, returned as an integer. |
seller.shopName | string | Shop display name. |
seller.shopIcon | string | Shop icon image URL. |
seller.shopUrl | string | Link to the shop page. |
seller.taoShopUrl | string | Another shop link returned for this listing. |
seller.sellerType | string | Seller type code reported by the marketplace. |
seller.creditLevel | string | Seller credit level reported as text. |
seller.allItemCount | integer | Reported count of items in the shop. |
seller.newItemCount | integer | Reported count of new items in the shop. |
seller.showShopLinkIcon | boolean | Whether the presentation metadata indicates that the shop link icon is shown. |
seller.evaluates | array | Ratings reported by the marketplace for the shop. |
seller.evaluates[] | object | One reported shop rating. |
seller.evaluates[].title | string | Display title of the shop rating criterion. |
seller.evaluates[].score | string | Reported score for the specified criterion, returned as text. |
seller.evaluates[].level | string | Reported level code for the score. |
seller.evaluates[].type | string | Reported rating criterion type code. |
itemTrade | object | Sales and payment information returned with the item. |
itemTrade.soldQuantityTotal | string | Reported total quantity sold, returned as display text. |
itemTrade.paymentList | array | Payment options displayed with the product. |
itemTrade.paymentList[] | object | One displayed payment option. |
itemTrade.paymentList[].name | string | Display name of the payment option. |
itemTrade.paymentList[].logo | string | Logo image URL for the payment option. |
merchantReturnRegion | array | Regions listed for merchant returns. |
merchantReturnRegion[] | string | A region listed for merchant returns. |
service | object | Merchant service information associated with the item. |
service.remarkUrl | string | Link provided for the service details. |
Reviews28 fields
data
| Field | Type | Description |
|---|---|---|
rate | object | Review breakdown and selected reviews in the product detail. |
rate.totalCount | string | Reported total number of reviews, returned as text. |
rate.hasAppendCount | string | Reported count of reviews with follow-up content, returned as text. |
rate.hasMediaCount | string | Reported count of reviews with media, returned as text. |
rate.hasNextPage | boolean | Whether the review preview indicates that more reviews are available. |
rate.keywords | array | Review keywords and their reported counts. |
rate.keywords[] | object | One review keyword displayed for the product. |
rate.keywords[].word | string | Display text of the review keyword. |
rate.keywords[].count | integer | Reported count for the review keyword. |
rate.keywords[].labelId | string | Review keyword label ID, returned as text. |
rate.keywords[].type | integer | Reported type code of the review keyword. |
rate.rateList | array | Reviews included with the item details. |
rate.rateList[] | object | One review returned for the item. |
rate.rateList[].userName | string | Displayed name of the reviewer. |
rate.rateList[].headPic | string | Image URL for the reviewer’s displayed avatar. |
rate.rateList[].content | string | Text content of the review. |
rate.rateList[].dateTime | string | Reported publication time text for the review. |
rate.rateList[].skuInfo | string | Displayed SKU information associated with the review. |
rate.rateList[].commentScore | string | Reported review score as text. |
rate.rateList[].likeCount | integer | Reported number of likes on the review. |
rate.rateList[].images | array | Image URLs attached to the review, when available. |
rate.rateList[].images[] | string | URL of an image attached to the review. |
rate.rateList[].appendRateList | array | Follow-up content for the review, when returned. |
rate.rateList[].appendRateList[] | object | One follow-up entry for the review. |
rate.rateList[].appendRateList[].content | string | Text content of the follow-up review. |
rate.rateList[].appendRateList[].appendIntervalDay | string | Reported interval in days before the follow-up, returned as text. |
rate.rateList[].appendRateList[].images | array | Image URLs attached to the follow-up review, when available. |
rate.rateList[].appendRateList[].images[] | string | URL of an image attached to the follow-up review. |
Product questions10 fields
data
| Field | Type | Description |
|---|---|---|
itemAskDOList | array | Product questions and included answers, when available. |
itemAskDOList[] | object | One question associated with the product. |
itemAskDOList[].askContent | string | Text of the question. |
itemAskDOList[].askUserNick | string | Displayed nickname of the person who asked the question. |
itemAskDOList[].createTime | string | Reported creation time text for the question. |
itemAskDOList[].answerList | array | Answers included with the question. |
itemAskDOList[].answerList[] | object | One answer to the product question. |
itemAskDOList[].answerList[].answerContent | string | Text of the answer. |
itemAskDOList[].answerList[].createTime | string | Reported creation time text for the answer. |
itemAskDOList[].answerList[].userNick | string | Displayed nickname of the person who answered. |
Main listing display22 fields
data
| Field | Type | Description |
|---|---|---|
mainItemInfo | object | Display information for the main listing. |
mainItemInfo.itemId | string | Item ID as text in the listing summary. |
mainItemInfo.itemName | string | Display name in the listing summary. |
mainItemInfo.pic | string | Product image URL in the listing summary. |
mainItemInfo.url | string | Product link in the listing summary, when provided. |
mainItemInfo.afterCouponAmountPrice | string | Displayed after-coupon price text in the listing summary. |
mainItemInfo.zkFinalPrice | string | Displayed final discounted price in the listing summary, when provided. |
mainItemInfo.promotionModel | object | Promotion presentation details, when returned. |
mainItemInfo.promotionModel.promotionPriceModel | object | Reported amounts and display text for the promotion. |
mainItemInfo.promotionModel.promotionPriceModel.promotionPrice | string | Reported amount of the promotional price, returned as text. |
mainItemInfo.promotionModel.promotionPriceModel.promotionPriceDescDisplay | string | Displayed description for the promotional price. |
mainItemInfo.promotionModel.promotionPriceModel.promotionPriceDisplay | string | Displayed text for the promotional price. |
mainItemInfo.promotionModel.promotionPriceModel.zkPrice | string | Reported discounted price amount, returned as text. |
mainItemInfo.promotionModel.promotionPriceModel.zkPriceDisplay | string | Displayed text for the discounted price. |
mainItemInfo.promotionModel.promotionTagModel | array | Labels used to display the promotion. |
mainItemInfo.promotionModel.promotionTagModel[] | object | One promotion display label. |
mainItemInfo.promotionModel.promotionTagModel[].tagDisplay | string | Displayed promotion label text. |
mainItemInfo.promotionModel.promotionTagModel[].tagType | string | Reported type code for the promotion label. |
mainItemInfo.promotionModel.promotionTagModel[].tagTypeDisplay | string | Displayed name of the promotion label type. |
mainItemInfo.taobaoPromotionModel | object | Marketplace promotion summary, when available. |
mainItemInfo.taobaoPromotionModel.finalPromotionInfo | object | Final promotional price information returned in the summary. |
mainItemInfo.taobaoPromotionModel.finalPromotionInfo.finalPromotionPrice | string | Reported final promotional price as text. |