获取热门商品列表
您可以使用本接口获取电商商品库中基于 TikTok 用户互动数据的热门商品，至多可获取前 50 个热门商品。
注意
- 商品库分析数据在您向电商商品库上传至少 20 个商品的 24 小时后生成。
- 商品库分析数据在每日 UTC 时间上午约 4 点刷新。
请求
地址 https://business-api.tiktok.com/open_api/v1.3/catalog/insight/product/get/
方法 GET
Header
|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
|Access-Token {必填}|string|授权访问令牌。可以通过[获取访问令牌](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162)接口获取。|
参数
|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
| bc_id {必填} | string | 商务中心 ID。 <br><br>若想获取您有权访问的商务中心列表，可使用[/bc/get/](1737115687501826.html)。 |
| catalog_id {必填}| string | 商品库 ID。 <br> 需指定一个包含至少 20 个商品的电商商品库。 <br> <br>若想获取某个商务中心中的电商商品库列表，可使用 [/catalog/get/](1740315452868610.html)，筛选对应的 `catalog_type` 为 `ECOM` 的 `catalog_id` 值。 若想验证商品库中包含的商品至少为 20 个，可使用 [/catalog/overview/](1740492470201345.html)，查看返回的字段 `approved`，`rejected` 和 `processing` 的值之和是否大于等于 20。 |
| filtering | object | 筛选条件 |
###| category_ids {+条件必填} | string[] | 若传入了 `filtering`，需至少指定 `category_ids`，`brands`和 `availabilities` 其中之一。 <br><br> TikTok 商品类目 ID 列表，可用于筛选分析数据。<br><br>最大数量：50。 <br><br>需传入 [/catalog/insight/filter/get/](1805640864553985.html) 返回的 `category_id` 字段值中的一个或多个商品类目 ID。 |
###| brands {+条件必填} | string[] | 若传入了 `filtering`，需至少指定 `category_ids`，`brands`和 `availabilities` 其中之一。 <br><br> 商品品牌名称列表，可用于筛选分析数据。<br><br>最大数量：50。<br><br> 需传入 [/catalog/insight/filter/get/](1805640864553985.html) 返回的 `brands` 字段值中的一个或多个品牌名称。 |
###| availabilities {+条件必填} | string[] | 若传入了 `filtering`，需至少指定 `category_ids`，`brands`和 `availabilities` 其中之一。 <br><br> 商品的库存状态列表，可用于筛选分析数据。<br><br> 枚举值：<ul><li>`IN_STOCK`：有库存。</li><li>`AVAILABLE_FOR_ORDER`：可订购。</li><li>`PREORDER`：可预订。</li><li>`OUT_OF_STOCK`：缺货。</li><li>`DISCONTINUED`：停售。</li></ul><br> 需传入 [/catalog/insight/filter/get/](1805640864553985.html) 返回的 `availabilities` 字段值中的一个或多个库存状态。 |
示例
(code curl http)
curl --location --request GET 'https://business-api.tiktok.com/open_api/v1.3/catalog/insight/product/get/?bc_id={{bc_id}}&catalog_id={{catalog_id}}' \
--header 'Access-Token: {{Access-Token}}' \
(/code)
返回
|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
|code |number| 返回码。完整返回码列表及描述，参见 [附录 - 返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。|
|message |string| 返回信息。更多信息参见 [附录 - 返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。 |
|request_id |string| 请求的日志ID，唯一标识一个请求。 |
|data |object| 返回数据。 |
#| product_insights | object[] | 电商商品库中的热门商品，至多可获取前 50 个热门商品，列表按热门程度倒序排列。 <br><br> 例如，列表中第一个商品排名第 1，即最热门的商品，第二个商品排名第 2，即第二热门的商品。 |
##| product_id | string | 系统生成的商品 ID。 |
##| image_url | string | 商品主图的 URL。 |
##| title | string | 商品标题。 |
##| description | string | 关于商品的简短描述。 |
##| sku_id | string | 广告主自定义的商品 SKU ID。 |
##| category_info | object | 商品的商品类目的有关信息。 |
###| category_id | string | 商品的 TikTok 商品类目 ID，由三个类目层级及 # 号分隔符构成，格式为"第一层级的 ID#第二层级的 ID#第三层级的 ID"。<br><br> 示例：`601152#842248#601302`。 |
###| level_info | object | 类目所属层级的详情。 |
####| level_id_1 | string | TikTok 商品类目第一层级的 ID。 |
####| level_name_1 | string | TikTok 商品类目第一层级的名称。 |
####| level_id_2 | string | TikTok 商品类目第二层级的 ID。 |
####| level_name_2 | string | TikTok 商品类目第二层级的名称。 |
####| level_id_3 | string | TikTok 商品类目第三层级的 ID。 |
####| level_name_3 | string | TikTok 商品类目第三层级的名称。 |
##| brand | string | 商品品牌名称。 |
##| price | object | 商品价格信息。 |
###| price | float | 商品基础价格。 |
###| currency | string | 价格对应的货币单位。 <br><br>若您未提供本字段，将使用商品库定向国家的货币单位为默认货币单位。 |
###| sale_price | float | 商品优惠价格。 |
###| sale_price_effective_date | string[] | 商品优惠的开始和结束日期和时间。 |
##| availability | string | 商品库存情况。<br><br> 枚举值：<ul><li>`IN_STOCK`：有库存。</li><li>`AVAILABLE_FOR_ORDER`：可订购。</li><li>`PREORDER`：可预订。</li><li>`OUT_OF_STOCK`：缺货。</li><li>`DISCONTINUED`：停售。</li></ul> |
示例
(code Success-Response http)
HTTPS/1.1 200 OK
{
"code": 0,
"message": "OK",
"request_id": "{{request_id}}",
"data": {
"product_insights": [
{
"availability": "OUT_OF_STOCK",
"brand": "{{brand}}",
"category_info": {
"category_id": "605248#905224#906248",
"level_info": {
"level_id_1": "605248",
"level_id_2": "905224",
"level_id_3": "906248",
"level_name_1": "Fashion Accessories",
"level_name_2": "Clothes Accessories",
"level_name_3": "Headwear"
}
},
"description": "{{description}}",
"image_url": "{{image_url}}",
"price": {
"currency": "USD",
"price": 22.99,
"sale_price": 17.99,
"sale_price_effective_date": null
},
"product_id": "{{product_id}}",
"sku_id": "{{sku_id}}",
"title": "{{title}}"
},
{
"availability": "OUT_OF_STOCK",
"brand": "{{brand}}",
"category_info": {
"category_id": "601152#842376#601276",
"level_info": {
"level_id_1": "601152",
"level_id_2": "842376",
"level_id_3": "601276",
"level_name_1": "Womenswear & Underwear",
"level_name_2": "Women's Bottoms",
"level_name_3": "Jeans"
}
},
"description": "{{description}}",
"image_url": "{{image_url}}",
"price": {
"currency": "USD",
"price": 57.99,
"sale_price": 49.99,
"sale_price_effective_date": null
},
"product_id": "{{product_id}}",
"sku_id": "{{sku_id}}",
"title": "{{title}}"
}
]
}
}
(/code)