Skip to content

淘宝和天猫商品详情 API (V1) ​

GET
接口健康状态
健康 可用 少量可用 基本不可用 暂无数据
正在加载健康状态…

通过V1接口按商品ID获取淘宝或天猫商品详情。用于直接商品查找,进行目录研究、商品监控或电商分析。

使用提示 ​

适用条件 · 价格

返回商品原价。部分商品提供SKU价格,其他商品可能没有。

支持能力 · 属性

提供分组商品参数表。

支持能力 · SKU 选项

提供SKU标识符、规格选项和数量信息。

支持能力 · 主图和轮播图

提供商品主图和轮播图。

适用条件 · 描述图片

描述图片包含在描述HTML中,需要提取;不提供单独的图片列表。

适用条件

某些商品可能无法通过此接口获取。

请求参数 ​

参数名位置类型必填默认值说明
tokenquerystring是-此 API 服务的访问令牌。
itemIdquerystring是-淘宝/天猫上的唯一商品标识符(商品ID)。

代码示例 ​

bash
curl --max-time 120 -X GET 'https://api.justoneapi.com/api/taobao/get-item-detail/v1?token=YOUR_API_KEY&itemId=VALUE'
text
我想使用 JustOneAPI 提供的“商品详情 (V1)”接口。
接入地址: https://api.justoneapi.com。
接口路径: /api/taobao/get-item-detail/v1?token=YOUR_API_KEY&itemId=VALUE
接口地址: BASE_URL + /api/taobao/get-item-detail/v1?token=YOUR_API_KEY&itemId=VALUE
HTTP 方法: GET
身份验证: 在 URL 中传入 token 查询参数。
OpenAPI 定义: https://docs.justoneapi.com/openapi/taobao-and-tmall/product-details-v1-zh.json

请求参数说明:
- token (query): 此 API 服务的访问令牌。 (必填)
- itemId (query): 淘宝/天猫上的唯一商品标识符(商品ID)。 (必填)

返回格式: 请根据实际 Content-Type 安全处理 JSON 或文本响应。

响应处理与错误码:
1. 需通过返回体中的 "code" 字段判断业务结果(code 为 0 表示成功)。
2. 超时建议:建议将请求超时时间设置为 120 秒;如果 120 秒偏长,请至少设置为 60 秒,但可能会有少量请求因超时而未接收到结果。
3. 业务码说明:
   - 0: 成功
   - 100: Token 无效或已失效
   - 301: 采集失败,请重试
   - 302: 超出速率限制
   - 303: 超出每日配额
   - 400: 参数错误
   - 500: 内部服务器错误
   - 600: 权限不足
   - 601: 账户余额不足
   - 602: TOKEN 限额超限
4. code 601 表示账户共享余额不足。code 602 表示当前 API TOKEN 自身的累计消费上限已达到。TOKEN 限额不是资金划拨,多个 TOKEN 仍共享同一个账户余额。

请帮我用我擅长的编程语言写一个脚本来调用这个接口,并处理返回结果。
python
import requests

BASE_URL = "https://api.justoneapi.com"  # 由 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"; // 由 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"; // 由 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" // 由 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'; // 由 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;
}

返回字段 ​

业务成功时(code = 0)的主要返回字段。

商品基本信息14 个字段

data

淘宝或天猫商品详情,按实际返回商品、价格、规格和关联内容。

字段类型说明
itemobject所查商品的信息。
item.itemIdinteger淘宝或天猫商品编号,以整数返回。
item.titlestring商品的展示标题。
item.categoryIdstring商品所属类目编号,以字符串返回。
item.rootCategoryIdstring商品所属一级类目编号,以字符串返回。
item.locationstring商品显示的所在地。
item.sellCountstring商品显示的销量文本。
item.seoItemTypestring平台返回的商品类型标签。
itemDescstring商品描述的 HTML 文本,其中可以包含详情图片链接。
itemExistboolean商品详情中返回的商品存在标记。
successboolean商品详情数据内的成功标记。
areaLimitboolean是否为该商品标记了地区限制。
freeShippingboolean是否为该商品标记了包邮。
skuIdinteger商品信息同时返回的 SKU 编号。
图片与视频21 个字段

data.item

字段类型说明
imagesarray商品图片地址列表,保留返回顺序。
images[]string一张商品图片的地址。
videosarray商品详情提供的视频列表。
videos[]object一条商品视频。
videos[].videoUrlstring商品视频地址。
videos[].coverUrlstring商品视频的封面图片地址。
videos[].uploadDatestring商品视频返回的上传日期文本。
kolVideosarray商品关联的创作者视频列表,可能缺省。
kolVideos[]object一条与该商品关联的创作者视频。
kolVideos[].nickstring创作者的展示昵称。
kolVideos[].coverUrlstring创作者视频的封面图片地址。
kolVideos[].video5sUrlstring该视频的短预览地址。
kolVideos[].videoUrlstring创作者视频地址。
beehiveContentobject商品页面附带的关联内容。
beehiveContent.accountNamestring关联内容的账号展示名称。
beehiveContent.contentAggreNamestring关联内容合集的展示名称。
beehiveContent.contentAggreUrlstring关联内容合集链接,可能缺省。
beehiveContent.contentCoverstring关联内容的封面图片地址。
beehiveContent.contentDetailUrlstring关联内容的详情链接。
beehiveContent.contentSummarystring关联内容的摘要。
beehiveContent.contentTitlestring关联内容的展示标题。
价格与优惠券22 个字段

data

字段类型说明
creativeTextstring商品关联的促销展示文本,可能缺省。
itemPriceobject商品级的价格及促销展示信息。
itemPrice.pricestring商品价格文本,可能缺省。
itemPrice.originalPricestring返回的商品原价文本。
itemPrice.promotionPricestring返回的商品促销价文本。
itemPrice.promotionNamestring商品促销活动的展示名称。
itemPrice.hasRangePriceboolean返回的价格是否标记为区间价。
itemPrice.exchangePriceHKDstring换算为港元的价格展示文本。
itemPrice.exchangePriceTWDstring换算为新台币的价格展示文本。
itemPrice.startTimestring价格信息返回的开始时间文本。
itemPrice.endTimestring价格信息返回的结束时间文本。
itemPrice.remarkstring价格信息附带的说明文本。
couponobject商品返回的优惠券信息。
coupon.couponobject回包内附带的优惠券详情。
coupon.coupon.couponClickUrlstring优惠券链接,可能缺省。
coupon.coupon.couponInfostring优惠券的展示说明。
coupon.coupon.couponPriceinteger优惠券金额,以返回的整数形式表示。
coupon.coupon.couponStartTimestring优惠券返回的开始时间文本。
coupon.coupon.couponEndTimestring优惠券返回的结束时间文本。
coupon.coupon.couponRemainCountinteger返回的优惠券剩余数量。
coupon.coupon.couponTotalCountinteger返回的优惠券总数量。
coupon.coupon.itemUrlstring优惠券信息附带的商品链接。
SKU 与库存21 个字段

data

字段类型说明
itemSkuDOobjectSKU 明细、规格组合及可选项。
itemSkuDO.skuListobject以 SKU 编号字符串为键的明细映射。部分商品的规格明细缺少价格字段。
itemSkuDO.skuList.{key}object映射键对应的 SKU 明细。
itemSkuDO.skuList.{key}.skuIdintegerSKU 编号,以整数返回。
itemSkuDO.skuList.{key}.propPathstringSKU 规格路径。每项以冒号连接属性编号和值编号,多项用分号隔开。
itemSkuDO.skuList.{key}.quantitystring该 SKU 返回的数量,以字符串表示。
itemSkuDO.skuList.{key}.pricestring该 SKU 的价格文本,可能缺省。
itemSkuDO.skuList.{key}.priceMoneyinteger该 SKU 价格的整数表示,可能缺省。
itemSkuDO.skuPVPairListarraySKU 编号及对应规格路径列表。
itemSkuDO.skuPVPairList[]object一条 SKU 及其规格组合。
itemSkuDO.skuPVPairList[].skuIdintegerSKU 编号,以整数返回。
itemSkuDO.skuPVPairList[].propPathstringSKU 规格路径。每项以冒号连接属性编号和值编号,多项用分号隔开。
itemSkuDO.skuPropertyListarray用于区分商品 SKU 的规格属性列表。
itemSkuDO.skuPropertyList[]object一项规格属性及其可选值。
itemSkuDO.skuPropertyList[].pidinteger规格属性编号,以整数返回。
itemSkuDO.skuPropertyList[].namestring规格属性的展示名称。
itemSkuDO.skuPropertyList[].propertyValuesarray该规格属性的可选值列表。
itemSkuDO.skuPropertyList[].propertyValues[]object该规格属性的一项可选值。
itemSkuDO.skuPropertyList[].propertyValues[].vidinteger规格选项编号,以整数返回。
itemSkuDO.skuPropertyList[].propertyValues[].namestring规格选项的展示名称。
itemSkuDO.skuPropertyList[].propertyValues[].imagestring规格选项的图片地址,可能缺省。
商品属性6 个字段

data

字段类型说明
propsobject商品展示的分组属性。
props.groupPropsarray使用平台原始组名和属性名的属性分组列表。
props.groupProps[]object以属性组名为键的对象。
props.groupProps[].{key}array映射键对应分组的属性列表。
props.groupProps[].{key}[]object以属性展示名称为键的对象。
props.groupProps[].{key}[].{key}string键所对应属性的展示值文本。
店铺与交易28 个字段

data

字段类型说明
sellerobject商品返回的店铺及卖家信息。
seller.shopIdinteger平台店铺编号,以整数返回。
seller.userIdinteger平台卖家账号编号,以整数返回。
seller.shopNamestring店铺展示名称。
seller.shopIconstring店铺图标地址。
seller.shopUrlstring店铺页面链接。
seller.taoShopUrlstring商品详情附带的另一种店铺链接。
seller.sellerTypestring平台返回的卖家类型编码。
seller.creditLevelstring卖家信用等级文本。
seller.allItemCountinteger返回的店铺商品数量。
seller.newItemCountinteger返回的店铺新品数量。
seller.showShopLinkIconboolean展示信息中是否标记显示店铺链接图标。
seller.evaluatesarray平台返回的店铺评分列表。
seller.evaluates[]object一项店铺评分。
seller.evaluates[].titlestring店铺评分项的展示名称。
seller.evaluates[].scorestring该评分项返回的分数文本。
seller.evaluates[].levelstring评分所对应的等级编码。
seller.evaluates[].typestring返回的评分项类型编码。
itemTradeobject商品返回的销量及支付方式信息。
itemTrade.soldQuantityTotalstring返回的累计销量展示文本。
itemTrade.paymentListarray商品显示的支付方式列表。
itemTrade.paymentList[]object一种展示的支付方式。
itemTrade.paymentList[].namestring支付方式的展示名称。
itemTrade.paymentList[].logostring支付方式的图标地址。
merchantReturnRegionarray返回的商家退货地区列表。
merchantReturnRegion[]string一个列出的商家退货地区。
serviceobject商品关联的商家服务信息。
service.remarkUrlstring商家服务说明链接。
商品评价28 个字段

data

字段类型说明
rateobject商品详情附带的评价统计及评价记录。
rate.totalCountstring返回的评价总数文本。
rate.hasAppendCountstring返回的含追评评价数量文本。
rate.hasMediaCountstring返回的含图片或视频评价数量文本。
rate.hasNextPageboolean评价预览是否标记还有更多评价。
rate.keywordsarray评价关键词及其对应计数。
rate.keywords[]object一项商品评价关键词。
rate.keywords[].wordstring评价关键词的展示文本。
rate.keywords[].countinteger该评价关键词的计数。
rate.keywords[].labelIdstring评价关键词标签编号,以字符串返回。
rate.keywords[].typeinteger返回的评价关键词类型编码。
rate.rateListarray商品详情中附带的评价列表。
rate.rateList[]object商品的一条评价记录。
rate.rateList[].userNamestring评价用户的展示名称。
rate.rateList[].headPicstring评价用户的头像地址。
rate.rateList[].contentstring商品评价正文。
rate.rateList[].dateTimestring评价返回的发布时间文本。
rate.rateList[].skuInfostring评价对应的商品规格展示信息。
rate.rateList[].commentScorestring评价分数文本。
rate.rateList[].likeCountinteger接口返回的评价点赞数。
rate.rateList[].imagesarray评价附带的图片地址列表,可能缺省。
rate.rateList[].images[]string一张评价配图的地址。
rate.rateList[].appendRateListarray该评价的追评列表,可能缺省。
rate.rateList[].appendRateList[]object一条追评记录。
rate.rateList[].appendRateList[].contentstring追评正文。
rate.rateList[].appendRateList[].appendIntervalDaystring返回的追评间隔天数文本。
rate.rateList[].appendRateList[].imagesarray追评附带的图片地址列表,可能缺省。
rate.rateList[].appendRateList[].images[]string一张追评配图的地址。
商品问答10 个字段

data

字段类型说明
itemAskDOListarray商品问答及附带回答,可能缺省。
itemAskDOList[]object一条商品相关问题。
itemAskDOList[].askContentstring提问正文。
itemAskDOList[].askUserNickstring提问用户的展示昵称。
itemAskDOList[].createTimestring提问返回的发布时间文本。
itemAskDOList[].answerListarray该问题附带的回答列表。
itemAskDOList[].answerList[]object一条商品问题的回答。
itemAskDOList[].answerList[].answerContentstring回答正文。
itemAskDOList[].answerList[].createTimestring回答返回的发布时间文本。
itemAskDOList[].answerList[].userNickstring回答用户的展示昵称。
主商品展示22 个字段

data

字段类型说明
mainItemInfoobject主商品展示信息。
mainItemInfo.itemIdstring主商品展示中的商品编号,以字符串返回。
mainItemInfo.itemNamestring主商品展示中的商品名称。
mainItemInfo.picstring主商品展示中的商品图片地址。
mainItemInfo.urlstring主商品展示中的商品链接,可能缺省。
mainItemInfo.afterCouponAmountPricestring主商品展示中的券后价文本。
mainItemInfo.zkFinalPricestring主商品展示中的最终折扣价文本,可能缺省。
mainItemInfo.promotionModelobject促销展示信息,可能缺省。
mainItemInfo.promotionModel.promotionPriceModelobject促销的返回金额及展示文本。
mainItemInfo.promotionModel.promotionPriceModel.promotionPricestring返回的促销价格金额文本。
mainItemInfo.promotionModel.promotionPriceModel.promotionPriceDescDisplaystring促销价格的展示说明。
mainItemInfo.promotionModel.promotionPriceModel.promotionPriceDisplaystring促销价格的展示文本。
mainItemInfo.promotionModel.promotionPriceModel.zkPricestring返回的折扣价格金额文本。
mainItemInfo.promotionModel.promotionPriceModel.zkPriceDisplaystring折扣价格的展示文本。
mainItemInfo.promotionModel.promotionTagModelarray用于展示促销活动的标签列表。
mainItemInfo.promotionModel.promotionTagModel[]object一项促销展示标签。
mainItemInfo.promotionModel.promotionTagModel[].tagDisplaystring促销标签的展示文本。
mainItemInfo.promotionModel.promotionTagModel[].tagTypestring返回的促销标签类型编码。
mainItemInfo.promotionModel.promotionTagModel[].tagTypeDisplaystring促销标签类型的展示名称。
mainItemInfo.taobaoPromotionModelobject平台促销汇总信息,可能缺省。
mainItemInfo.taobaoPromotionModel.finalPromotionInfoobject促销汇总中返回的最终促销价信息。
mainItemInfo.taobaoPromotionModel.finalPromotionInfo.finalPromotionPricestring接口返回的最终促销价文本。

响应示例 ​

正在加载响应示例…