淘宝/天猫店铺商品搜索API（taobao.item_search_shop）返回值详解

一、API核心功能

taobao.item_search_shop 是淘宝/天猫开放平台提供的接口，用于通过卖家ID（seller_id） 或**店铺ID（shop_id）**检索指定店铺内的所有商品信息。该接口支持分页查询、排序（按价格、销量、新品等），是获取店铺商品全量数据的核心工具。

二、返回值结构详解

API返回的JSON数据包含以下核心字段，结构示例如下：

json

|---------------------------------------------------------------------------------------------------|
| { |
| "seller_id": "898146183", |
| "page": "1", |
| "real_total_results": "113", |
| "total_results": "113", |
| "page_size": 10, |
| "page_count": 11, |
| "items": [ |
| { |
| "num_iid": "592020103246", |
| "pic_url": "//img.alicdn.com/bao/uploaded/O1CN01naTRO81UulqDd41W6_!!6000000002578-0-yinhe.jpg", |
| "title": "多功能激光翻页笔充电款ppt遥控器笔教师用演讲投影仪笔多媒体遥控笔幻灯片翻页器讲课红外线笔教学电子希沃", |
| "price": "18.9", |
| "orginal_price": "18.9", |
| "sales": 10000, |
| "shop_title": "carkoci旗舰店", |
| "detail_url": "https://item.taobao.com/item.htm?id=592020103246" |
| }, |
| { |
| "num_iid": "709182446951", |
| "pic_url": "//img.alicdn.com/bao/uploaded/O1CN013Zf9dN1IvR4DqjGZO_!!6000000000955-0-yinhe.jpg", |
| "title": "触屏电容笔ipad平板手机通用触控笔适用于苹果华为小米apple pencil磁吸手写笔学习机学生绘画剪辑安卓点触", |
| "price": "6.8", |
| "orginal_price": "6.8", |
| "sales": 5000, |
| "shop_title": "carkoci旗舰店", |
| "detail_url": "https://item.taobao.com/item.htm?id=709182446951" |
| } |
| ] |
| } |

1. 基础信息字段

• seller_id：卖家ID，唯一标识商品所属的店铺。
• page：当前页码，用于分页查询。
• real_total_results 与 total_results：实际返回的商品数量与总商品数量（通常一致）。
• page_size：每页显示的商品数量（如示例中的10条/页）。
• page_count ：总页数，帮助开发者计算分页逻辑（如总页数 = ceil(总结果数 / 每页数量)）。

2. 商品列表字段（items数组）

每个商品对象包含以下核心字段：

• num_iid ：商品唯一ID，用于标识具体商品（如592020103246）。
• pic_url ：商品主图URL，支持展示商品外观（如//img.alicdn.com/...）。
• title：商品标题，包含关键词和描述信息（如"多功能激光翻页笔充电款..."）。
• price 与 orginal_price ：
  • price ：当前售价（如18.9元）。
  • orginal_price ：原价（与price相同表示无折扣）。
• sales ：商品销量，反映市场热度（如10000笔）。
• shop_title：店铺名称（如"carkoci旗舰店"）。
• detail_url ：商品详情页链接，引导用户跳转至淘宝/天猫页面（如https://item.taobao.com/...）。

3. 排序与分页参数

• 排序（sort） ：
  • 支持按new（新品）、bid（价格）、sale（销量）排序。
  • 价格排序可加_前缀实现降序（如_bid表示价格从高到低）。
• 分页逻辑 ：
  • 通过page和page_size控制数据加载，避免一次性请求过多数据。
  • 示例：若总页数为11页，每页10条，则第2页的URL参数为page=2。

三、典型应用场景

1. 商品列表展示 ：
   • 使用title、pic_url、price展示商品基础信息。
   • 结合sales和price实现销量或价格排序。
2. 数据监控与分析 ：
   • 提取sales和price数据，分析商品销售趋势及价格敏感度。
   • 通过seller_id和shop_title监控竞品店铺动态。
3. 个性化推荐 ：
   • 基于用户历史行为（如浏览过的num_iid），推荐相似商品或关联商品。
   • 结合category_id（若存在）实现品类级推荐。

四、注意事项

1. 参数有效性 ：
   • shop_id参数在部分版本中可能已失效，建议优先使用seller_id。
2. 数据更新 ：
   • 商品信息可能动态变化，需定期调用API更新本地数据。
3. 性能优化 ：
   • 对返回的商品列表进行缓存，减少重复请求。
   • 合理设计分页逻辑，避免一次性加载过多数据导致性能问题。

五、示例代码（Python）

python

|------------------------------------------------------------------------|
| import requests |
| |
| def search_shop_items(seller_id, page=1, page_size=10, sort="sale"): |
| url = "https://api.taobao.com/item_search_shop" |
| params = { |
| "seller_id": seller_id, |
| "page": page, |
| "page_size": page_size, |
| "sort": sort |
| } |
| response = requests.get(url, params=params) |
| return response.json() |
| |
| # 示例调用 |
| data = search_shop_items(seller_id="898146183", page=1, sort="_bid") |
| print(data) |

通过以上解析，开发者可清晰理解taobao.item_search_shop API的返回值结构，并高效应用于商品检索、数据分析及个性化推荐等场景。