某书关键词搜索商品接口（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 更多
]
}
六、高频坑位提示
sales=-1 ≠ 0，是商家选择隐藏销量，请勿当成“0 销量”过滤。
价格区间商品（多 SKU）务必用 price.min / price.max 展示，否则用户会看到“89 元起”。
total 是预估值，翻页到 50 页以后可能返回空数组，请结合 has_more 判断。
优惠券 stock=0 时，前端应置灰“已抢光”，避免误导。
图片后缀 ~tplv-icva 为小红书自动压缩参数，如需要原图，请去掉后缀或替换为 ~tplv-obj.
七、实战 3 行计算
Python

折扣率

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 反查商品」、「实时销量监控」等进阶接口，留言告诉我，下篇继续拆解。

如遇任何疑问或有进一步的需求，请随时与我私信或者评论联系。