Skip to content

Taobao and Tmall Product Details API (V1) ​

GET
API health status
Healthy Available Limited Mostly unavailable No data
Loading health status...

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 ​

NameInTypeRequiredDefaultDescription
tokenquerystringYes-Access token for this API service.
itemIdquerystringYes-Unique product identifier on Taobao/Tmall (item ID).

Code Samples ​

bash
curl --max-time 120 -X GET 'https://api.justoneapi.com/api/taobao/get-item-detail/v1?token=YOUR_API_KEY&itemId=VALUE'
text
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.
python
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")
js
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`);
  }
}
java
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");
        }
    }
}
go
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
<?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.

FieldTypeDescription
itemobjectProduct information for the requested item.
item.itemIdintegerTaobao or Tmall item ID, returned as an integer.
item.titlestringDisplay title of the listing.
item.categoryIdstringCategory ID assigned to the item, returned as text.
item.rootCategoryIdstringTop-level category ID assigned to the item, returned as text.
item.locationstringLocation displayed for the item.
item.sellCountstringSales count text displayed for the item.
item.seoItemTypestringPlatform listing type label returned for the item.
itemDescstringProduct description as HTML text. Description image links can appear inside the markup.
itemExistbooleanItem existence flag reported in the product detail.
successbooleanSuccess flag reported inside the product detail data.
areaLimitbooleanWhether a regional restriction is reported for the item.
freeShippingbooleanWhether the item is marked as offering free shipping.
skuIdintegerSKU ID returned alongside the product information.
Images and videos21 fields

data.item

FieldTypeDescription
imagesarrayProduct image URLs in the order returned.
images[]stringURL of a product image.
videosarrayVideos returned with the listing.
videos[]objectOne product video.
videos[].videoUrlstringURL for the product video.
videos[].coverUrlstringCover image URL for the product video.
videos[].uploadDatestringUpload date text reported for the product video.
kolVideosarrayCreator videos associated with the listing, when returned.
kolVideos[]objectOne video from a creator associated with the listing.
kolVideos[].nickstringDisplay nickname of the creator.
kolVideos[].coverUrlstringCover image URL for the creator video.
kolVideos[].video5sUrlstringURL provided for the short video preview.
kolVideos[].videoUrlstringURL for the creator video.
beehiveContentobjectRelated content shown with the product.
beehiveContent.accountNamestringDisplay name of the related content account.
beehiveContent.contentAggreNamestringDisplay name of the related content collection.
beehiveContent.contentAggreUrlstringLink to the related content collection, when available.
beehiveContent.contentCoverstringCover image URL for the related content.
beehiveContent.contentDetailUrlstringLink to the related content details.
beehiveContent.contentSummarystringSummary text for the related content.
beehiveContent.contentTitlestringDisplay title of the related content.
Prices and coupons22 fields

data

FieldTypeDescription
creativeTextstringPromotional display text associated with the item, when available.
itemPriceobjectItem-level pricing and promotion display information.
itemPrice.pricestringItem price text returned for the listing, when available.
itemPrice.originalPricestringReported original item price as text.
itemPrice.promotionPricestringReported item promotional price as text.
itemPrice.promotionNamestringDisplay name of the item promotion.
itemPrice.hasRangePricebooleanWhether the price information is marked as a range.
itemPrice.exchangePriceHKDstringDisplayed price converted to Hong Kong dollars.
itemPrice.exchangePriceTWDstringDisplayed price converted to New Taiwan dollars.
itemPrice.startTimestringReported start time text for the price information.
itemPrice.endTimestringReported end time text for the price information.
itemPrice.remarkstringDisplay note provided with the price information.
couponobjectCoupon information returned for the item.
coupon.couponobjectCoupon details embedded in the response.
coupon.coupon.couponClickUrlstringLink provided for the coupon, when available.
coupon.coupon.couponInfostringDisplayed coupon description.
coupon.coupon.couponPriceintegerReported coupon amount as an integer value.
coupon.coupon.couponStartTimestringReported start time text for the coupon.
coupon.coupon.couponEndTimestringReported end time text for the coupon.
coupon.coupon.couponRemainCountintegerReported number of coupons remaining.
coupon.coupon.couponTotalCountintegerReported total number of coupons.
coupon.coupon.itemUrlstringItem listing link provided with the coupon information.
SKUs and quantity21 fields

data

FieldTypeDescription
itemSkuDOobjectSKU details, specification combinations, and selectable options.
itemSkuDO.skuListobjectSKU map whose keys are SKU IDs represented as strings. Pricing fields can be absent for some items.
itemSkuDO.skuList.{key}objectDetails of the SKU identified by the map key.
itemSkuDO.skuList.{key}.skuIdintegerSKU ID, returned as an integer.
itemSkuDO.skuList.{key}.propPathstringSKU specification path. Each pair joins a property ID and value ID with a colon, and multiple pairs are separated by semicolons.
itemSkuDO.skuList.{key}.quantitystringReported quantity for this SKU, returned as text.
itemSkuDO.skuList.{key}.pricestringReported price text for this SKU, when available.
itemSkuDO.skuList.{key}.priceMoneyintegerReported integer representation of this SKU price, when available.
itemSkuDO.skuPVPairListarrayList of SKU IDs and their specification paths.
itemSkuDO.skuPVPairList[]objectOne SKU and its selected specification combination.
itemSkuDO.skuPVPairList[].skuIdintegerSKU ID, returned as an integer.
itemSkuDO.skuPVPairList[].propPathstringSKU specification path. Each pair joins a property ID and value ID with a colon, and multiple pairs are separated by semicolons.
itemSkuDO.skuPropertyListarraySpecification properties that define the item variants.
itemSkuDO.skuPropertyList[]objectOne specification property and its options.
itemSkuDO.skuPropertyList[].pidintegerSpecification property ID, returned as an integer.
itemSkuDO.skuPropertyList[].namestringDisplay name of the specification property.
itemSkuDO.skuPropertyList[].propertyValuesarraySelectable values for the specification property.
itemSkuDO.skuPropertyList[].propertyValues[]objectOne option value for the specification property.
itemSkuDO.skuPropertyList[].propertyValues[].vidintegerOption value ID, returned as an integer.
itemSkuDO.skuPropertyList[].propertyValues[].namestringDisplay name of the option value.
itemSkuDO.skuPropertyList[].propertyValues[].imagestringImage URL for the option value, when available.
Product attributes6 fields

data

FieldTypeDescription
propsobjectGrouped product attributes displayed for the item.
props.groupPropsarrayAttribute groups with platform-provided group and attribute names.
props.groupProps[]objectAn object keyed by attribute group name.
props.groupProps[].{key}arrayList of attributes for the group identified by the map key.
props.groupProps[].{key}[]objectAn object keyed by the displayed attribute name.
props.groupProps[].{key}[].{key}stringDisplayed text value of the attribute named by the key.
Shop and trade28 fields

data

FieldTypeDescription
sellerobjectShop and seller information returned with the item.
seller.shopIdintegerMarketplace shop ID, returned as an integer.
seller.userIdintegerMarketplace account ID of the seller, returned as an integer.
seller.shopNamestringShop display name.
seller.shopIconstringShop icon image URL.
seller.shopUrlstringLink to the shop page.
seller.taoShopUrlstringAnother shop link returned for this listing.
seller.sellerTypestringSeller type code reported by the marketplace.
seller.creditLevelstringSeller credit level reported as text.
seller.allItemCountintegerReported count of items in the shop.
seller.newItemCountintegerReported count of new items in the shop.
seller.showShopLinkIconbooleanWhether the presentation metadata indicates that the shop link icon is shown.
seller.evaluatesarrayRatings reported by the marketplace for the shop.
seller.evaluates[]objectOne reported shop rating.
seller.evaluates[].titlestringDisplay title of the shop rating criterion.
seller.evaluates[].scorestringReported score for the specified criterion, returned as text.
seller.evaluates[].levelstringReported level code for the score.
seller.evaluates[].typestringReported rating criterion type code.
itemTradeobjectSales and payment information returned with the item.
itemTrade.soldQuantityTotalstringReported total quantity sold, returned as display text.
itemTrade.paymentListarrayPayment options displayed with the product.
itemTrade.paymentList[]objectOne displayed payment option.
itemTrade.paymentList[].namestringDisplay name of the payment option.
itemTrade.paymentList[].logostringLogo image URL for the payment option.
merchantReturnRegionarrayRegions listed for merchant returns.
merchantReturnRegion[]stringA region listed for merchant returns.
serviceobjectMerchant service information associated with the item.
service.remarkUrlstringLink provided for the service details.
Reviews28 fields

data

FieldTypeDescription
rateobjectReview breakdown and selected reviews in the product detail.
rate.totalCountstringReported total number of reviews, returned as text.
rate.hasAppendCountstringReported count of reviews with follow-up content, returned as text.
rate.hasMediaCountstringReported count of reviews with media, returned as text.
rate.hasNextPagebooleanWhether the review preview indicates that more reviews are available.
rate.keywordsarrayReview keywords and their reported counts.
rate.keywords[]objectOne review keyword displayed for the product.
rate.keywords[].wordstringDisplay text of the review keyword.
rate.keywords[].countintegerReported count for the review keyword.
rate.keywords[].labelIdstringReview keyword label ID, returned as text.
rate.keywords[].typeintegerReported type code of the review keyword.
rate.rateListarrayReviews included with the item details.
rate.rateList[]objectOne review returned for the item.
rate.rateList[].userNamestringDisplayed name of the reviewer.
rate.rateList[].headPicstringImage URL for the reviewer’s displayed avatar.
rate.rateList[].contentstringText content of the review.
rate.rateList[].dateTimestringReported publication time text for the review.
rate.rateList[].skuInfostringDisplayed SKU information associated with the review.
rate.rateList[].commentScorestringReported review score as text.
rate.rateList[].likeCountintegerReported number of likes on the review.
rate.rateList[].imagesarrayImage URLs attached to the review, when available.
rate.rateList[].images[]stringURL of an image attached to the review.
rate.rateList[].appendRateListarrayFollow-up content for the review, when returned.
rate.rateList[].appendRateList[]objectOne follow-up entry for the review.
rate.rateList[].appendRateList[].contentstringText content of the follow-up review.
rate.rateList[].appendRateList[].appendIntervalDaystringReported interval in days before the follow-up, returned as text.
rate.rateList[].appendRateList[].imagesarrayImage URLs attached to the follow-up review, when available.
rate.rateList[].appendRateList[].images[]stringURL of an image attached to the follow-up review.
Product questions10 fields

data

FieldTypeDescription
itemAskDOListarrayProduct questions and included answers, when available.
itemAskDOList[]objectOne question associated with the product.
itemAskDOList[].askContentstringText of the question.
itemAskDOList[].askUserNickstringDisplayed nickname of the person who asked the question.
itemAskDOList[].createTimestringReported creation time text for the question.
itemAskDOList[].answerListarrayAnswers included with the question.
itemAskDOList[].answerList[]objectOne answer to the product question.
itemAskDOList[].answerList[].answerContentstringText of the answer.
itemAskDOList[].answerList[].createTimestringReported creation time text for the answer.
itemAskDOList[].answerList[].userNickstringDisplayed nickname of the person who answered.
Main listing display22 fields

data

FieldTypeDescription
mainItemInfoobjectDisplay information for the main listing.
mainItemInfo.itemIdstringItem ID as text in the listing summary.
mainItemInfo.itemNamestringDisplay name in the listing summary.
mainItemInfo.picstringProduct image URL in the listing summary.
mainItemInfo.urlstringProduct link in the listing summary, when provided.
mainItemInfo.afterCouponAmountPricestringDisplayed after-coupon price text in the listing summary.
mainItemInfo.zkFinalPricestringDisplayed final discounted price in the listing summary, when provided.
mainItemInfo.promotionModelobjectPromotion presentation details, when returned.
mainItemInfo.promotionModel.promotionPriceModelobjectReported amounts and display text for the promotion.
mainItemInfo.promotionModel.promotionPriceModel.promotionPricestringReported amount of the promotional price, returned as text.
mainItemInfo.promotionModel.promotionPriceModel.promotionPriceDescDisplaystringDisplayed description for the promotional price.
mainItemInfo.promotionModel.promotionPriceModel.promotionPriceDisplaystringDisplayed text for the promotional price.
mainItemInfo.promotionModel.promotionPriceModel.zkPricestringReported discounted price amount, returned as text.
mainItemInfo.promotionModel.promotionPriceModel.zkPriceDisplaystringDisplayed text for the discounted price.
mainItemInfo.promotionModel.promotionTagModelarrayLabels used to display the promotion.
mainItemInfo.promotionModel.promotionTagModel[]objectOne promotion display label.
mainItemInfo.promotionModel.promotionTagModel[].tagDisplaystringDisplayed promotion label text.
mainItemInfo.promotionModel.promotionTagModel[].tagTypestringReported type code for the promotion label.
mainItemInfo.promotionModel.promotionTagModel[].tagTypeDisplaystringDisplayed name of the promotion label type.
mainItemInfo.taobaoPromotionModelobjectMarketplace promotion summary, when available.
mainItemInfo.taobaoPromotionModel.finalPromotionInfoobjectFinal promotional price information returned in the summary.
mainItemInfo.taobaoPromotionModel.finalPromotionInfo.finalPromotionPricestringReported final promotional price as text.

Response Example ​

Loading the response example...