健康知识 API：搜索知识接入实战（关键词 / 分类 / 分页）
# 健康知识 API：搜索知识接入实战（关键词 / 分类 / 分页）
- **接口/接入点**：健康知识 · 搜索知识 `90-87`（免费）
- **请求方式**：POST / GET ｜ **返回格式**：JSON ｜ **鉴权**：URL 携带 `appKey`
- **适用人群**：全栈开发者 ｜ **阅读时间**：约 9 分钟
## 核心要点
- 搜索知识接口三个参数：`key`（搜索关键词）、`tid`（分类 id，来自分类列表）、`page`（页码，每页最大返回 20 条）。
- 文档未在 schema 中把 `key` 标为 required，但关键词是搜索的必要输入，建议必传；`tid`/`page` 选填。
- 返回核心是 `pagebean`：`allNum`（总条数）、`allPages`（总页数）、`maxResult`（每页最大数）、`contentlist`（当前页数据）。
## Why：搜索是内容型接口的主战场
对内容产品来说，"分类浏览"只是入口，"搜索"才是用户找内容的主要方式。健康知识 API 的搜索接口支持关键词 + 分类 + 分页三重能力，配合返回的分页元数据，可以很容易做出"搜索框 + 分页列表"的完整体验。本文给出可落地的实现。
## What：接口速览
| 项目 | 说明 |
|------|------|
| 接口地址 | `https://route.showapi.com/90-87?appKey={your_appKey}` |
| 请求参数（form） | `key`(string 搜索关键词)、`tid`(string 类目id)、`page`(string 请求页数) |
| 返回 | `showapi_res_body.pagebean`：`allPages`/`currentPage`/`allNum`/`maxResult`/`contentlist[]` |
| 超时 | 官方读写超时 15 秒 |
> 说明：官方 OpenAPI schema 的 `required` 列表为空（未强制标注必填），但 `key` 作为搜索关键词是必要输入，实际调用建议必传；`tid`、`page` 为可选筛选/翻页参数。
## How：关键词检索 + 分类筛选 + 分页
**Python（requests）**
```python
import requests
APP_KEY = "YOUR_APPKEY"
URL = "https://route.showapi.com/90-87"
params = {
"key": "感冒", # 搜索关键词（建议必传）
"tid": "101", # 分类 id，来自分类列表；不传则全部分类
"page": "1", # 页码，每页最大返回 20 条
}
try:
resp = requests.post(URL, params={"appKey": APP_KEY}, data=params, timeout=15)
resp.raise_for_status()
data = resp.json()
except requests.RequestException as e:
print("请求失败:", e)
raise
body = data["showapi_res_body"]
if body.get("ret_code") != "0":
print("业务错误:", body.get("ret_code"), body.get("remark"))
else:
pb = body["pagebean"]
print(f"总条数={pb['allNum']} 总页数={pb['allPages']} 当前页={pb['currentPage']} 每页最大={pb['maxResult']}")
for it in pb["contentlist"]:
print(it["id"], it["title"], "| 分类:", it.get("tname"), "| 时间:", it.get("ctime"))
```
**cURL**
```bash
curl -X POST "https://route.showapi.com/90-87?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
-d "key=感冒&tid=101&page=1"
```
**Node.js（fetch）**
```javascript
const APP_KEY = "YOUR_APPKEY";
const url = `https://route.showapi.com/90-87?appKey=${APP_KEY}`;
const body = new URLSearchParams({ key: "感冒", tid: "101", page: "1" });
const data = await (await fetch(url, {
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded" },
body,
})).json();
const pb = data.showapi_res_body.pagebean;
console.log(`总条数=${pb.allNum} 总页数=${pb.allPages}`);
pb.contentlist.forEach((it) => console.log(it.id, it.title));
```
### 翻页逻辑
- `page` 从 `1` 开始递增；文档明确每页最大返回 20 条（`maxResult` 即每页上限）。
- 用 `currentPage` 与 `allPages` 判断是否还有下一页；到达 `allPages` 即停止。
- 列表项 `id` 可传给[查看单条详情](https://www.showapi.com/guides/health-knowledge-detail-90)接口获取长文。
## 返回示例与解析
```json
{
"showapi_res_code": 0,
"showapi_res_error": "",
"showapi_res_id": "b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6",
"showapi_res_body": {
"ret_code": "0",
"remark": "",
"pagebean": {
"allPages": 3,
"currentPage": 1,
"allNum": 45,
"maxResult": 20,
"contentlist": [
{
"id": "100001",
"title": "感冒了怎么办",
"keywords": "感冒,发烧",
"tname": "疾病科普",
"media_name": "健康编辑部",
"tid": "101",
"wapurl": "https://example.com/a/100001",
"ctime": "2024-01-15 10:00:00",
"intro": "感冒常见症状与居家应对建议。",
"url": "https://example.com/a/100001"
}
]
}
}
}
```
> 字段值（如具体 id、标题）为结构示意，实际内容以接口返回为准。
## 进阶 / 边界
- **每页 20 条是硬上限**：`maxResult` 即每页最大数，请求更大 page size 也不会超过该值；做"加载更多"时注意按 20 条一页分批。
- **`tid` 与 `key` 组合**：只传 `key` 全分类搜；传 `tid` 限定分类；两者可叠加。
- **空结果**：`contentlist` 为空数组可能表示无匹配，可结合 `allNum=0` 判断并展示"无结果"提示。
## FAQ
**Q：key 到底是不是必填？**
A：官方 schema 未标 required，但 `key` 是搜索关键词、为搜索的必要输入，实际调用建议必传；只传 `tid`/`page` 而无 `key` 的行为以接口实际返回为准。
**Q：每页最多能返回多少条？**
A：文档明确每页最大返回 20 条（`maxResult` 字段体现），超出按 20 条上限处理。
**Q：搜索支持模糊匹配吗？**
A：接口按关键词检索，具体匹配规则由后端决定，文档未说明；建议以实际返回结果为准，必要时做关键词归一化。
**Q：搜索结果里的 id 能直接取详情吗？**
A：可以，`contentlist[].id` 作为[查看单条详情](https://www.showapi.com/guides/health-knowledge-detail-90)接口的 `id` 参数。
## 相关能力与下一步阅读
- [健康知识 API：查看单条知识详情与长文渲染](https://www.showapi.com/guides/health-knowledge-detail-90)
- [健康知识 API 分页与总量处理：pagebean 的 allPages / allNum / maxResult](https://www.showapi.com/guides/health-knowledge-pagination-90)
- [健康知识 API：分类列表怎么用？先拿分类 ID 再精准筛选](https://www.showapi.com/guides/health-knowledge-category-90)
- **本系列共 12 篇**：查看[健康知识 API 使用指南总目录](https://www.showapi.com/guides/health-knowledge-guides-90)
