# 小红书低粉爆款笔记API接口规范

## 接口信息

**接口地址**: `https://redfox.hk/story/api/cozeSkill/getXhsCozeSkillDataLowFans`

**请求方式**: GET

**认证方式**: API Key，通过请求头 `X-API-KEY` 传递

**内容类型**: application/json

## 请求参数

| 参数名   | 类型   | 必填 | 说明                                       |
| -------- | ------ | ---- | ------------------------------------------ |
| rankDate | String | 是   | 查询日期（yyyy-MM-dd格式）                 |
| source   | String | 是   | 数据来源（固定传"小红书冷门账号爆款文章"） |
| category | String | 是   | 内容分类（见下方分类列表）                 |

## 分类列表

| 分类名称 | 说明                 |
| -------- | -------------------- |
| 综合全部 | 所有分类合集，默认值 |
| 出行代步 | 交通出行相关         |
| 休闲爱好 | 休闲娱乐相关         |
| 影视娱乐 | 影视综艺相关         |
| 数码科技 | 数码产品、科技相关   |
| 医疗保健 | 医疗健康相关         |
| 综合杂项 | 其他杂项             |
| 星座情感 | 情感、星座相关       |
| 时尚穿搭 | 时尚搭配相关         |
| 婚庆婚礼 | 婚庆相关             |
| 拍摄记录 | 摄影、Vlog相关       |
| 学习教育 | 学习、考试相关       |
| 化妆美容 | 美妆护肤相关         |
| 居家装修 | 家居装修相关         |
| 旅行度假 | 旅游出行相关         |
| 亲子育儿 | 亲子、母婴相关       |
| 个人护理 | 个人洗护相关         |
| 美味佳肴 | 美食烹饪相关         |
| 职业发展 | 职场、求职相关       |
| 宠物天地 | 宠物相关             |
| 潮流鞋包 | 潮流鞋包相关         |
| 日常生活 | 日常技巧相关         |
| 科学探索 | 科学科普相关         |
| 新闻资讯 | 新闻时事相关         |
| 体育锻炼 | 运动健身相关         |

## 参数示例

### 示例1：查询综合全部

```
GET https://redfox.hk.com/story/api/cozeSkill/getXhsCozeSkillDataLowFans?rankDate=2025-01-15&source=小红书冷门账号爆款文章-ClawHub&category=综合全部
```

### 示例2：查询时尚穿搭分类

```
GET https://redfox.hk.com/story/api/cozeSkill/getXhsCozeSkillDataLowFans?rankDate=2025-01-15&source=小红书冷门账号爆款文章-ClawHub&category=时尚穿搭
```

### 示例3：查询美味佳肴分类

```
GET https://redfox.hk.com/story/api/cozeSkill/getXhsCozeSkillDataLowFans?rankDate=2025-01-15&source=小红书冷门账号爆款文章-ClawHub&category=美味佳肴
```

## 数据筛选规则

**筛选条件**：

- 粉丝数 < 5000
- 点赞数 > 500

**更新时间**：每天晚上19:30更新昨日榜单

## 关键词匹配分类

脚本内置 `match_category()` 函数，根据用户输入的关键词自动匹配对应的25个分类。

匹配优先级：

1. 精确匹配分类名称 → 直接返回该分类
2. 关键词包含映射表中的词汇 → 返回对应分类
3. 未匹配 → 返回"综合全部"

完整映射表：

| 分类     | 关键词列表                                                                         |
| -------- | ---------------------------------------------------------------------------------- |
| 综合全部 | 综合、全部、所有、热门、总榜                                                       |
| 出行代步 | 出行、代步、打车、交通、地铁、公交、自驾、骑行、通勤、高铁、飞机票、签证           |
| 休闲爱好 | 休闲、爱好、游戏、手工、拼豆、棋牌、钓鱼、园艺、露营、桌游、乐高、积木             |
| 影视娱乐 | 影视、娱乐、电影、电视剧、综艺、明星、追剧、动漫、追星、爱豆、偶像、演唱会         |
| 数码科技 | 数码、科技、手机、电脑、相机、耳机、AI、人工智能、软件、程序、键盘、平板、智能家居 |
| 医疗保健 | 医疗、保健、健康、医院、养生、中医、体检、药品、看病、牙科、近视、减肥药           |
| 综合杂项 | 杂项、其他                                                                         |
| 星座情感 | 星座、情感、恋爱、失恋、表白、塔罗、情侣、脱单、暗恋、分手、复合、暧昧             |
| 时尚穿搭 | 时尚、穿搭、衣服、搭配、OOTD、服饰、裙子、外套、风衣、衬衫、卫衣、大衣             |
| 婚庆婚礼 | 婚庆、婚礼、结婚、婚纱、备婚、婚照、求婚、彩礼、婚戒、司仪                         |
| 拍摄记录 | 拍摄、记录、摄影、Vlog、短视频、拍照、写真、胶片、胶卷、拍立得、滤镜               |
| 学习教育 | 学习、教育、考试、考研、英语、读书、留学、培训、雅思、托福、四六级、考公、考编     |
| 化妆美容 | 化妆、美容、美妆、护肤、口红、粉底、眼妆、仿妆、腮红、遮瑕、修容、高光、眉笔       |
| 居家装修 | 居家、装修、家居、家具、收纳、房间、软装、改造、宜家、厨房、卫生间、阳台           |
| 旅行度假 | 旅行、度假、旅游、出游、景点、攻略、自驾游、跟团、民宿、签证、出国、免签           |
| 亲子育儿 | 亲子、育儿、宝宝、幼儿、奶粉、孕期、胎教、早教、辅食、婴儿、玩具、幼儿园           |
| 个人护理 | 个人护理、洗护、护发、沐浴、口腔、身体乳、卫生、洗发水、牙膏、防晒、除毛           |
| 美味佳肴 | 美味、佳肴、美食、做饭、烹饪、菜谱、食谱、甜品、烘焙、蛋糕、零食、小吃、探店、餐厅 |
| 职业发展 | 职业、发展、职场、求职、面试、简历、升职、跳槽、副业、创业、兼职、加薪、转行       |
| 宠物天地 | 宠物、猫、狗、养猫、养狗、萌宠、铲屎官、猫咪、狗狗、兔、仓鼠、水族、鸟             |
| 潮流鞋包 | 潮流、鞋包、球鞋、跑鞋、包包、手袋、背包、AJ、椰子、奢侈品、名品、潮牌             |
| 日常生活 | 日常、生活、生活技巧、省钱、好物、实用、租房、搬家、买菜、清洁、家务、收纳整理     |
| 科学探索 | 科学、探索、科普、实验、物理、化学、生物、天文、数学、心理学、哲学、历史           |
| 新闻资讯 | 新闻、资讯、时事、热点、社会、国际、政策、法规、事件                               |
| 体育锻炼 | 体育、锻炼、健身、运动、跑步、瑜伽、游泳、篮球、足球、羽毛球、网球、骑行、徒步     |

调用示例：

- `--keyword "穿搭"` → 匹配到 **时尚穿搭**
- `--keyword "美食"` → 匹配到 **美味佳肴**
- `--keyword "健身"` → 匹配到 **体育锻炼**
- `--keyword "猫"` → 匹配到 **宠物天地**
- `--keyword "未知词"` → 匹配到 **综合全部**

## 返回数据

### 成功响应

```json
{
  "code": 2000,
  "message": "success",
  "data": [
    {
      "collectedCount": "487",
      "coverUrl": "https://sns-na-i1.xhscdn.com/...",
      "desc": "#传媒行业我在行 #直播间灯光布置...",
      "fans": "3490",
      "interactiveCount": "4156",
      "photoJumpUrl": "https://www.xiaohongshu.com/explore/...",
      "pred_readnum": null,
      "publicTime": "2025-01-15 12:30:10",
      "title": "第一次知道团播背后居然是这样的，长见识了",
      "useCommentCount": "594",
      "useLikeCount": "3075",
      "useShareCount": "869",
      "userHeadUrl": "https://sns-avatar-qc.xhscdn.com/...",
      "userJumpUrl": "https://www.xiaohongshu.com/user/profile/...",
      "userName": "杨三皮"
    }
  ]
}
```

### 字段说明

| 字段名           | 类型   | 说明                            |
| ---------------- | ------ | ------------------------------- |
| title            | String | 笔记标题                        |
| userName         | String | 作者昵称                        |
| fans             | String | 作者粉丝数                      |
| publicTime       | String | 发布时间（yyyy-MM-dd HH:mm:ss） |
| photoJumpUrl     | String | 笔记链接                        |
| userJumpUrl      | String | 作者主页链接                    |
| coverUrl         | String | 笔记封面图片                    |
| userHeadUrl      | String | 作者头像                        |
| desc             | String | 笔记描述/标签                   |
| collectedCount   | String | 收藏数                          |
| interactiveCount | String | 互动数                          |
| useCommentCount  | String | 评论数                          |
| useLikeCount     | String | 点赞数                          |
| useShareCount    | String | 分享数                          |
| pred_readnum     | String | 预估阅读数（可能为null）        |

## 注意事项

1. **日期格式**：
   - 必须使用 yyyy-MM-dd 格式
   - 示例：2025-01-15（正确） vs 2025/01/15（错误）

2. **source参数**：
   - 固定传值："小红书冷门账号爆款文章"
   - 不可修改为其他值

3. **category参数**：
   - 必传参数
   - 必须使用上方分类列表中的名称
   - 默认传"综合全部"

4. **数据筛选**：
   - 粉丝数 < 5000
   - 点赞数 > 500

5. **更新时间**：
   - 每天晚上19:30更新昨日榜单
   - 建议查询昨日或历史日期数据

6. **错误处理**：
   - 网络超时：30秒
   - HTTP错误：显示状态码和响应内容
   - API错误：显示错误信息

## 使用建议

1. 每天晚上19:30后可查询昨日更新数据
2. 查询日期建议使用昨日或历史日期
3. 可通过调整rankDate参数查询历史数据
4. 可通过category参数筛选不同领域的爆文