某书关键词搜索商品接口（smallredbook.item_search）返回值全景解读

一、接口定位

smallredbook.item_search 是小红书开放平台提供的「关键词搜索商品」标准接口。
一句话：给定任意关键词，一次性拿到 20 个结构化商品卡片，可用于选品、比价、内容挂车、竞品监控等场景。

---

二、最简调用示例

GET https://open.xiaohongshu.com/api/smallredbook/item_search
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "keyword": "早C晚A精华",
  "sort": "composite",   // composite / sales / price_asc / price_desc
  "page": 1,
  "page_size": 20
}

---

三、返回顶层结构

字段	类型	说明
code	int	0 为成功，非 0 见 msg
msg	string	错误描述，成功为空
has_more	bool	是否有下一页
total	int	预估商品总量（上限 10 000）
items	array[object]	商品卡片列表，见下表

---

四、items 数组单个对象字段总览

下方「示例值」均来自真实回包（已脱敏）。

字段	类型	示例值	含义&特殊说明
item_id	string	"64f2058e000000002303c9c7"	商品唯一 ID，可用于 item_get 详情接口
title	string	"【早C晚A】VC视黄醇抗老公式精华 30ml"	商品标题，已去掉 HTML 标签
price	object	见 4.1	价格区间对象
cover	string	"https://ci.xiaohongshu.com/xxxx.jpg~tplv-icva..."	主图 512×512 WebP
sales	int	12800	历史总销量，-1 表示隐藏
rating	float	4.8	评分，5 分制，-1 表示无评分
reviews	int	3542	有效评价数
badges	array[string]	["自营", "七天无理由"]	商品角标
shop	object	见 4.2	店铺信息
coupons	array[object]	见 4.3	可用优惠券
tags	array[string]	["早C晚A", "抗氧化", "精华"]	平台提取的搜索相关标签
url	string	"https://www.xiaohongshu.com/goods/64f2058e..."	小红书站内落地页
created_at	string	"2024-11-01T12:34:56+08:00"	商品上架时间
last_updated	string	"2025-01-20T18:00:00+08:00"	最近一次价格/库存变更

---

4.1 price 对象

{
  "min": 89.00,
  "max": 179.00,
  "currency": "CNY",
  "unit": "瓶",
  "origin_min": 129.00,
  "origin_max": 229.00
}

• min/max：当前到手价区间（已计算活动价）

• origin_min/origin_max：划线价/原价，可用于计算折扣率

---

4.2 shop 对象

字段	类型	示例
shop_id	string	"5f2a1c3be4b08bb3c8970f2d"
shop_name	string	"XX美妆海外旗舰店"
shop_type	string	"flagship"	枚举：flagship / authorized / individual
shop_score	float	4.9	店铺综合体验分
fans	int	56000	店铺粉丝数

---

4.3 coupons 数组（可能为空）

[{
  "coupon_id": "189292991",
  "threshold": 99,        // 满 99
  "amount": 10,           // 减 10
  "start_time": "2026-01-20 00:00:00",
  "end_time": "2026-01-31 23:59:59",
  "stock": 850            // 剩余库存，-1 为不限
}]

---

五、完整返回示例（折叠版）

{
  "code": 0,
  "msg": "",
  "has_more": true,
  "total": 6320,
  "items": [
    {
      "item_id": "64f2058e000000002303c9c7",
      "title": "【早C晚A】VC视黄醇抗老公式精华 30ml",
      "price": { "min": 89, "max": 179, "currency": "CNY", "origin_min": 129 },
      "cover": "https://ci.xiaohongshu.com/xxxx.jpg~tplv-icva",
      "sales": 12800,
      "rating": 4.8,
      "reviews": 3542,
      "badges": ["自营", "七天无理由"],
      "shop": {
        "shop_id": "5f2a1c3be4b08bb3c8970f2d",
        "shop_name": "XX美妆海外旗舰店",
        "shop_type": "flagship",
        "shop_score": 4.9,
        "fans": 56000
      },
      "coupons": [{
        "coupon_id": "189292991",
        "threshold": 99,
        "amount": 10,
        "start_time": "2026-01-20 00:00:00",
        "end_time": "2026-01-31 23:59:59",
        "stock": 850
      }],
      "tags": ["早C晚A", "抗氧化", "精华"],
      "url": "https://www.xiaohongshu.com/goods/64f2058e000000002303c9c7",
      "created_at": "2024-11-01T12:34:56+08:00",
      "last_updated": "2025-01-20T18:00:00+08:00"
    }
    // ... 19 更多
  ]
}

---

六、高频坑位提示

1. sales=-1 ≠ 0，是商家选择隐藏销量，请勿当成“0 销量”过滤。

2. 价格区间商品（多 SKU）务必用 price.min / price.max 展示，否则用户会看到“89 元起”。

3. total 是预估值，翻页到 50 页以后可能返回空数组，请结合 has_more 判断。

4. 优惠券 stock=0 时，前端应置灰“已抢光”，避免误导。

5. 图片后缀 ~tplv-icva 为小红书自动压缩参数，如需要原图，请去掉后缀或替换为 ~tplv-obj.

---

七、实战 3 行计算

# 折扣率
discount = round(item["price"]["min"] / item["price"]["origin_min"] * 10, 1)
# 店铺转化率（经验公式）
cvr = item["sales"] / (item["reviews"] + 1) * 100
# 优惠力度
coupon_rate = item["coupons"][0]["amount"] / item["price"]["min"] if item["coupons"] else 0

---

八、版本更新日志（最近 3 次）

版本	日期	变更
v2.3.0	2025-12-15	新增 last_updated、coupon.stock
v2.2.8	2025-09-01	返回图片默认改为 WebP，节省 30% 流量
v2.2.5	2025-06-10	增加 shop_score、fans 字段

---

九、结语

掌握 smallredbook.item_search 的返回结构后，你可以：

• 10 分钟写出选品脚本

• 1 小时搭个“小红书比价小程序”

• 1 天完成竞品监控看板

如果还需要「根据笔记 ID 反查商品」、「实时销量监控」等进阶接口，留言告诉我，下篇继续拆解。