一、接口定位
smallredbook.item_search 是小红书开放平台提供的「关键词搜索商品」标准接口。一句话：给定任意关键词，一次性拿到 20 个结构化商品卡片，可用于选品、比价、内容挂车、竞品监控等场景。
二、最简调用示例
http
GET https://open.xiaohongshu.com/api/smallredbook/item_searchAuthorization: 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 对象
JSON
{
"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 数组（可能为空）
JSON
[{
"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 为不限}]五、完整返回示例（折叠版）
JSON
{
"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 反查商品」、「实时销量监控」等进阶接口，留言告诉我，下篇继续拆解。
如遇任何疑问或有进一步的需求，请随时与我私信或者评论联系。
