网络搜索热词排行返回字段全解：name/num/level/trend 一文读懂
# 网络搜索热词排行返回字段全解：name/num/level/trend 一文读懂
> 接口：网络搜索热词排行（apiCode=313，接入点 313-2） · 免费服务 · 返回格式 JSON · 适用人群：初级/中级开发者 · 阅读时间：约 6 分钟
## 核心要点
- 业务数据全在 `showapi_res_body` 里；`list` 是热搜词数组，系统级字段（`showapi_res_code` 等）在外层。
- 每条热搜含 4 个字段：`name`（词）、`num`（排名）、`level`（热度分）、`trend`（趋势）。
- `trend` 取值文档存在不一致：字段表写 `up/down/same`，返回示例出现 `rise`，代码需兼容。
## Why：为什么值得先把字段读透
字段理解错了，前端就会排错序、把"下降"显示成"上升"。这篇把每个字段的真实结构与取值讲清，并点出文档里那个容易踩的坑，省你后面返工。
## What：返回结构速览
| 项目 | 说明 |
|------|------|
| 系统级封装 | `showapi_res_body` 内含全部业务数据 |
| 业务数组 | `showapi_res_body.list`（Array） |
| 成功标记 | `showapi_res_body.ret_code`：`0` 为成功，其他为失败（文档未给完整枚举） |
| 单条字段 | `name` / `num` / `level` / `trend` |
## How：字段逐个看
```json
{
"showapi_res_code": 0,
"showapi_res_error": "",
"showapi_res_id": "ce135f6739294c63be0c021b76b6fbff",
"showapi_res_body": {
"list": [
{ "level": "22244", "name": "驴友瀑降不幸身亡", "num": "1", "trend": "rise" },
{ "level": "3566", "name": "女司机掰断方向盘", "num": "2", "trend": "rise" }
],
"ret_code": 0
}
}
```
### 字段对照表
| 字段 | 类型 | 示例 | 含义 | 注意 |
|------|------|------|------|------|
| `showapi_res_body.list` | Array | — | 热搜词列表 | 可能为空数组（该分类暂无热搜） |
| `list[].name` | String | 怒砸10亿为国护盘 | 热搜词 | 直接展示给用户 |
| `list[].num` | String | 11 | 排名 | 越小越靠前，按它排序 |
| `list[].level` | String | 22244 | 热度分 | 分高则排名高，衡量相对热度 |
| `list[].trend` | String | up / rise | 趋势 | **取值见下方"需修正项"** |
| `showapi_res_body.ret_code` | String | 0 | 状态 | `0` 成功，非 `0` 失败 |
### 关系图
```
showapi_res_body
├── ret_code : "0" ← 成功标记
└── list : [ ← 热搜词数组
{ name, num(排名), level(热度分), trend(趋势) }
]
```
## 返回示例与解析
完整示例见[5 分钟接入篇](https://www.showapi.com/guides/hotword-quickstart-313)。这里只强调两点：
1. `num` 与 `level` 不同：`num` 是名次，`level` 是热度分数；展示排序用 `num`，热度对比可用 `level`。
2. `trend` 不要写死判断。
## 进阶 / 边界（需修正项）
**`trend` 取值文档不一致**：字段表描述为 `up`=升 / `down`=降低 / `same`=持平，但同一接口的返回示例里写的是 `"trend":"rise"`。两者冲突，真实接口疑似返回 `rise` / `down` / `same`。
**建议写法（兼容两种）**：
```python
def trend_label(trend):
return {
"rise": "升", "up": "升",
"down": "降",
"same": "持平",
}.get(str(trend), str(trend))
```
这样无论接口返回 `rise` 还是 `up` 都能正确显示为"升"。更详细的趋势解读见[热搜趋势解读篇](https://www.showapi.com/guides/hotword-trend-313)。
## FAQ
**Q1：ret_code 有哪些值？分别代表什么？**
A1：文档仅标注 `0` 为成功、其他为失败，未给出完整枚举。代码按"非 0 即失败"处理，不要把未列出的数字解读为特定含义。
**Q2：list 为空正常吗？**
A2：正常。某分类某时刻可能确实无热搜数据，或 `tab`/`category` 传值不在支持范围内。
**Q3：level 和 num 为什么不是一一对应？**
A3：它们量纲不同——`num` 是名次（1、2、3…），`level` 是热度绝对值。不同分类的 `level` 之间没有横向可比性。
**Q4：trend 能用来预测明天热度吗？**
A4：不能。`trend` 只是相对上一统计周期的升降/持平标记，接口未提供预测数据，展示时标注"趋势"即可，不要做成预测。
**Q5：系统级字段 showapi_res_code 和 body 里的 ret_code 有什么区别？**
A5：外层 `showapi_res_code` 是平台级返回码（如网络/鉴权），`showapi_res_body.ret_code` 是业务级返回码。两者都为 `0` 才代表完全成功。
## 相关能力 / 下一步阅读
- [热搜趋势解读：trend 字段 up/down/same 与 rise 取值怎么用？](https://www.showapi.com/guides/hotword-trend-313)
- [5 分钟接入网络搜索热词排行：从注册到拿到第一条热搜榜](https://www.showapi.com/guides/hotword-quickstart-313)
- [搭建实时热搜看板：网络搜索热词排行 + 定时拉取的完整设计](https://www.showapi.com/guides/hotword-dashboard-313)
- **本系列共 12 篇**：查看[网络搜索热词排行开发指南总目录](https://www.showapi.com/guides/hotword-guides-313)
