5 分钟接入网络搜索热词排行：从注册到拿到第一条热搜榜
网络热搜词热搜榜API快速接入Python示例免费接口 # 5 分钟接入网络搜索热词排行：从注册到拿到第一条热搜榜
> 接口：网络搜索热词排行（apiCode=313，接入点 313-2 网络热搜词排行） · 免费服务 · 请求方式 POST/GET · 返回格式 JSON · 适用人群：新注册用户、初级开发者 · 阅读时间：约 5 分钟
## 核心要点
- 网络搜索热词排行是**免费**接口，只需一个 AppKey 即可调用，无需购买资源包。
- 调用本质：向 `https://route.showapi.com/313-2` 发送 `appKey`（查询参数）+ `tab`（表单必填）即可拿到热搜榜。
- 返回 `list` 数组，每项含 `name`（热搜词）、`num`（排名）、`level`（热度分）、`trend`（趋势）。
## Why：这跟我有什么关系
做新媒体、做资讯产品、做 AI 助手，都需要"现在大家在搜什么"。这个接口把多个搜索引擎的综合热度聚合好，你不用自己爬、不用买数据，免费就能拿到结构化热搜榜，直接喂给你的选题、看板或 Agent。
## What：前置条件与接口速览
| 项目 | 说明 |
|------|------|
| 接口地址 | `https://route.showapi.com/313-2?appKey={your_appKey}` |
| 接入点 | 313-2 网络热搜词排行（本篇）；另有 313-1 网络搜索热词分类查询 |
| 请求方式 | POST / GET |
| 鉴权 | 查询参数 `appKey`（在 [AppKey 管理](https://www.showapi.com/console#/myApp) 获取） |
| 必填参数 | `tab`（主分类，英文，如 `game`；可用 313-1 查全部可选值） |
| 计费 | 免费服务 |
| 返回格式 | JSON，业务数据在 `showapi_res_body` |
| 集成能力 | MCP 服务、OpenAPI 3.0 文档（见生态集成层文章） |
前置条件：已注册 ShowAPI 账号并拿到 AppKey。
## How：第一次调用
### 步骤 1 · 获取 AppKey
登录后进入 [AppKey 管理](https://www.showapi.com/console#/myApp)，复制任意一个应用的 AppKey。
### 步骤 2 · Python 调用（推荐）
```python
import requests
APP_KEY = "YOUR_APPKEY" # 替换为你的真实 AppKey
URL = "https://route.showapi.com/313-2"
def get_hotwords(tab, category=None, country=None, timeout=10):
# appKey 走查询参数；tab/category/country 走表单
resp = requests.post(
URL,
params={"appKey": APP_KEY},
data={"tab": tab, **({"category": category} if category else {}),
**({"country": country} if country else {})},
headers={"content-type": "application/x-www-form-urlencoded"},
timeout=timeout,
)
resp.raise_for_status()
body = resp.json().get("showapi_res_body", {})
if str(body.get("ret_code")) != "0":
raise RuntimeError(f"接口返回失败: ret_code={body.get('ret_code')}")
return body.get("list", [])
if __name__ == "__main__":
for item in get_hotwords("game")[:5]:
print(item.get("num"), item.get("name"), "热度", item.get("level"), item.get("trend"))
```
### 步骤 3 · cURL 调用
```bash
curl -X POST "https://route.showapi.com/313-2?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
-d "tab=game&category=&country="
```
### 步骤 4 · Node.js 调用
```javascript
const APP_KEY = "YOUR_APPKEY";
async function getHotwords(tab) {
const resp = await fetch(`https://route.showapi.com/313-2?appKey=${APP_KEY}`, {
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({ tab }).toString(),
});
const json = await resp.json();
const body = json.showapi_res_body;
if (String(body.ret_code) !== "0") throw new Error(`接口返回失败: ${body.ret_code}`);
return body.list;
}
getHotwords("game").then((list) => console.log(list.slice(0, 5)));
```
把 `YOUR_APPKEY` 换成真实密钥即可运行，终端会打印前 5 条热搜词。
## 返回示例与解析
```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
}
}
```
| 字段 | 类型 | 含义 |
|------|------|------|
| `name` | String | 热搜词 |
| `num` | String | 排名（越小越靠前） |
| `level` | String | 热度分，分高则排名高 |
| `trend` | String | 趋势：升 / 降 / 持平（取值见趋势解读篇） |
> 注意：`num` 是排名、`level` 是热度分，二者不是一回事。按 `num` 排序展示即可；`level` 可用来在同级分类里衡量相对热度。
## 进阶 / 边界
- `tab` 必填，且必须是接口支持的主分类（如 `game`、`novel`、`star`）。可用 313-1 接入点查全部可选 `tab` 与子分类，见[网络搜索热词分类查询（313-1）](https://www.showapi.com/guides/hotword-category-query-313)。
- 文档仅标注 `ret_code=0` 为成功，未给出完整错误码枚举；调用时按"非 0 即失败"处理即可，不要自行猜测具体错误码含义。
- 文档未标注限流/QPS，实际频率以平台为准，建议加基础重试与缓存（见[缓存策略篇](https://www.showapi.com/guides/hotword-cache-313)）。
## FAQ
**Q1：接口真的是免费的吗？**
A1：页面标注为"免费服务"，调用本身不计费、无需购买资源包；只需有效 AppKey。
**Q2：appKey 能写进前端代码吗？**
A2：不建议。AppKey 是账户凭证，应放在服务端环境变量，前端只请求你自己的后端。
**Q3：为什么我传了 tab 却返回空 list？**
A3：确认 `tab` 是接口支持的主分类英文值（用 313-1 核对）；部分分类下某个时间点可能确实无热搜数据。
**Q4：GET 和 POST 都能用吗？**
A4：文档标注支持 POST / GET。示例以 POST 表单为主；GET 时把 `tab` 等作为查询参数拼接即可。
**Q5：返回里的 trend 有时是 rise 有时是 up，到底哪个对？**
A5：文档字段表写的是 up/down/same，但返回示例出现 rise。这是文档不一致，我们在[热搜趋势解读篇](https://www.showapi.com/guides/hotword-trend-313)给出了兼容两种取值的写法。
## 相关能力 / 下一步阅读
- [网络搜索热词排行返回字段全解：name/num/level/trend 一文读懂](https://www.showapi.com/guides/hotword-response-fields-313)
- [网络搜索热词分类查询（313-1）：如何先拿到可查的 tab 与子分类](https://www.showapi.com/guides/hotword-category-query-313)
- [通过 MCP 在 AI 客户端（Cherry Studio/ChatBox）中直接调用网络搜索热词排行](https://www.showapi.com/guides/hotword-mcp-313)
- **本系列共 12 篇**：查看[网络搜索热词排行开发指南总目录](https://www.showapi.com/guides/hotword-guides-313)
