地区与子分类筛选：country/category 参数正确使用姿势
# 地区与子分类筛选：country/category 参数正确使用姿势
> 接口：网络搜索热词排行（apiCode=313，接入点 313-2） · 免费服务 · 返回格式 JSON · 适用人群：中级开发者、产品经理 · 阅读时间：约 6 分钟
## 核心要点
- 313-2 除必填 `tab` 外，还有两个可选参数：`category`（子分类，汉字）和 `country`（地区，汉字）。
- `category` 的合法取值来自 313-1 返回的 `category` 列表；`country` **并非所有分类都支持**，能否按地区筛选以实际返回/调用为准。
- 不传这两个参 → 返回该 `tab` 下的全量热搜；传了则按维度收窄。
## Why：为什么这两个参数容易用错
很多人一上来就传 `country="中国"` 想看地区榜，结果拿到空数据——因为该分类根本不支持地区维度。正确姿势是先拿 313-1 的分类树确认支持哪些子分类/地区，再决定传什么，避免无效请求和空结果。
## What：参数速览
| 参数 | 必填 | 类型 | 说明 |
|------|------|------|------|
| `tab` | 是 | String | 主分类英文键（如 `game`），用 313-1 核对 |
| `category` | 否 | String | 子分类（汉字，如"单机游戏"），取值见 313-1 |
| `country` | 否 | String | 地区（汉字），并非所有分类支持 |
## How：先确认、再筛选
### 步骤 1 · 用 313-1 看某 tab 有哪些子分类
参考[分类查询篇](https://www.showapi.com/guides/hotword-category-query-313)：313-1 返回的 `ret[].category` 即为 313-2 `category` 的合法取值。
### 步骤 2 · 带 category 查询
```python
import requests
APP_KEY = "YOUR_APPKEY"
def get_hotwords(tab, category=None, country=None):
resp = requests.post(
"https://route.showapi.com/313-2",
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=10,
).json()
body = resp.get("showapi_res_body", {})
if str(body.get("ret_code")) != "0":
raise RuntimeError(f"失败: {body.get('ret_code')}")
return body.get("list", [])
# 查 game 分类下的"单机游戏"子分类
print(get_hotwords("game", category="单机游戏")[:5])
```
### 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=%E5%8D%95%E6%9C%BA%E6%B8%B8%E6%88%8F&country="
```
## 返回示例与解析
返回结构与[返回字段全解篇](https://www.showapi.com/guides/hotword-response-fields-313)一致；传 `category` 后 `list` 仅含该子分类热搜，数量通常少于全量。
## 进阶 / 边界
- **`country` 不是万能的**：文档明确"并不是所有分类都能按地区分类"。调用前用 313-1 确认该 `tab` 是否提供地区维度；拿不准就先不传 `country`，拿到结果再说。
- **传了不支持的维度会怎样**：可能返回空 `list` 或全量（行为以接口实际为准），不要假设"传了就一定收窄"。
- `category`/`country` 为中文，注意 URL 编码（表单编码会自动处理，GET 时需手动编码）。
## FAQ
**Q1：不传 category/country 会报错吗？**
A1：不会，二者都是可选。不传返回该 `tab` 全量热搜。
**Q2：country 怎么知道某个分类支不支持？**
A2：先用 313-1 拉分类树，若对应主分类带有地区列表即可用 `country`；无则大概率不支持。
**Q3：category 传错字会怎样？**
A3：可能返回空或全量，按接口实际行为；建议取值严格来自 313-1 的 `category` 列表。
**Q4：category 和 country 能同时用吗？**
A4：可以一起传，接口会按两个维度收窄；是否同时生效以返回结果为准。
**Q5：中文参数需要编码吗？**
A5：用表单（`application/x-www-form-urlencoded`）提交时由库自动编码；用 GET 拼接需自行 `urlencode`。
## 相关能力 / 下一步阅读
- [网络搜索热词分类查询（313-1）：如何先拿到可查的 tab 与子分类](https://www.showapi.com/guides/hotword-category-query-313)
- [资讯聚合平台方案：多分类热搜聚合与去重](https://www.showapi.com/guides/hotword-news-aggregation-313)
- [网络搜索热词排行返回字段全解：name/num/level/trend 一文读懂](https://www.showapi.com/guides/hotword-response-fields-313)
- **本系列共 12 篇**：查看[网络搜索热词排行开发指南总目录](https://www.showapi.com/guides/hotword-guides-313)
