网络搜索热词分类查询（313-1）：如何先拿到可查的 tab 与子分类
# 网络搜索热词分类查询（313-1）：如何先拿到可查的 tab 与子分类
> 接口：网络搜索热词分类查询（apiCode=313，接入点 313-1） · 免费服务 · 返回格式 JSON · 适用人群：初级/中级开发者、产品经理 · 阅读时间：约 6 分钟
## 核心要点
- 313-1 是"分类目录"接口：返回各主分类 `tab` 及其子分类 `category` 列表，用来给 313-2 提供合法入参。
- 调用 313-2 前，先用 313-1 确认有哪些 `tab` 和可选 `category`/`country`，避免乱传值导致空结果。
- 文档缺口：313-1 的请求参数表只列了 `content-type` 头，未把 `tab` 列为入参，但返回体里包含 `tab`/`category`。本篇按"返回完整分类树"理解，不臆造入参。
## Why：为什么需要这一篇
313-2 的 `tab` 是必填项，且必须是接口支持的主分类（如 `game`、`novel`、`star`）。如果你硬编码一个不存在的分类，就会拿到空榜。313-1 就是官方给你的"合法取值清单"，先查它再查排行，工作流才稳。
## What：接入点速览
| 项目 | 说明 |
|------|------|
| 接口地址 | `https://route.showapi.com/313-1?appKey={your_appKey}` |
| 接入点 | 313-1 网络搜索热词分类查询 |
| 请求方式 | POST / GET |
| 鉴权 | 查询参数 `appKey` |
| 请求参数 | 文档仅列 `content-type` 头（⚠️ 见下方需修正项） |
| 返回 | `ret`（Array）：每项含 `tab`（主分类）、`category`（String[] 子分类） |
| 计费 | 免费服务 |
## How：先查分类，再查排行
### 步骤 1 · 拉取分类树
```python
import requests
APP_KEY = "YOUR_APPKEY"
URL = "https://route.showapi.com/313-1"
def get_categories(timeout=10):
resp = requests.post(
URL, params={"appKey": APP_KEY},
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("ret", [])
if __name__ == "__main__":
for item in get_categories():
print("主分类 tab =", item.get("tab"))
print(" 子分类:", item.get("category"))
```
### 步骤 2 · 用查到的 tab 去查排行
```python
# 拿到 tab（如 "game"）后，传入 313-2
from hotword_quickstart_helpers import get_hotwords # 见 quickstart 篇
print(get_hotwords("game")[:5])
```
### cURL
```bash
# 查分类
curl -X POST "https://route.showapi.com/313-1?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded"
# 用返回的 tab 查排行
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="
```
### Node.js
```javascript
const APP_KEY = "YOUR_APPKEY";
async function getCategories() {
const resp = await fetch(`https://route.showapi.com/313-1?appKey=${APP_KEY}`, {
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded" },
});
const json = await resp.json();
if (String(json.showapi_res_body.ret_code) !== "0")
throw new Error(`接口返回失败: ${json.showapi_res_body.ret_code}`);
return json.showapi_res_body.ret;
}
```
## 返回示例与解析
```json
{
"showapi_res_body": {
"ret": [
{
"category": ["全部类型","都市","玄幻","奇幻","历史","科幻","军事","游戏","武侠","现代言情","古代言情","幻想言情","青春"],
"tab": "novel"
}
],
"ret_code": 0,
"showapi_fee_code": 0
}
}
```
| 字段 | 类型 | 含义 |
|------|------|------|
| `ret[].tab` | String | 主分类英文键（传给 313-2 的 `tab`） |
| `ret[].category` | String[] | 该主分类下的子分类（汉字），可作 313-2 的 `category` |
| `ret_code` | Number | `0` 成功 |
## 进阶 / 边界（需修正项）
- **313-1 入参文档缺口**：接入点说明与返回体都涉及 `tab`，但请求参数表只列了 `content-type` 头，未把 `tab` 列为入参。本篇按"一次返回完整分类树"处理；如需按主分类过滤，建议先取全量再在本地按 `tab` 筛选，不要假设存在未文档化的入参。
- 并非所有主分类都有 `country`（地区）维度，是否支持地区以 313-1 返回的 `category` 是否含地区列表为准；具体见[地区与子分类筛选篇](https://www.showapi.com/guides/hotword-country-category-313)。
## FAQ
**Q1：313-1 和 313-2 必须一起用吗？**
A1：不是必须，但强烈建议。313-2 的 `tab` 必须合法，313-1 给你权威取值清单，避免硬编码出错。
**Q2：返回的 category 和 313-2 的 category 参数是一回事吗？**
A2：是。313-1 返回的 `category` 子分类，正是 313-2 可选 `category` 参数的合法取值。
**Q3：为什么我拿到的 category 里没有"地区"？**
A3：地区维度不在 `category` 里，而是部分分类额外支持 `country` 参数，且并非所有分类都支持。能否按地区筛选以实际调用为准。
**Q4：ret_code 在 313-1 是 Number、在 313-2 是 String，要紧吗？**
A4：文档两处类型标注不一致，但取值都是 `0` 表示成功。代码统一用 `str(ret_code) != "0"` 判断最稳妥。
**Q5：分类多久变一次？**
A5：文档未标注更新频率，建议按"小时级"缓存并在必要时刷新（见[缓存策略篇](https://www.showapi.com/guides/hotword-cache-313)）。
## 相关能力 / 下一步阅读
- [5 分钟接入网络搜索热词排行：从注册到拿到第一条热搜榜](https://www.showapi.com/guides/hotword-quickstart-313)
- [地区与子分类筛选：country/category 参数正确使用姿势](https://www.showapi.com/guides/hotword-country-category-313)
- [资讯聚合平台方案：多分类热搜聚合与去重](https://www.showapi.com/guides/hotword-news-aggregation-313)
- **本系列共 12 篇**：查看[网络搜索热词排行开发指南总目录](https://www.showapi.com/guides/hotword-guides-313)
