唐诗宋词元曲查询：title 名称查询为什么不支持模糊匹配？正确用法与避坑
# 唐诗宋词元曲查询：title 名称查询为什么不支持模糊匹配？正确用法与避坑
> 接口：唐诗宋词元曲等诗词查询（apiCode=1620）· 接入点 1620-5 名称查询诗词列表 · 免费 · 返回 JSON · 适用：调用 1620-5 的开发者 · 阅读约 5 分钟
## 核心要点
- 1620-5 的 `title` 参数**不支持模糊查询**，必须传入与数据源一致的**精确诗名**
- 常见报错根因：用别称/简称（如「赤壁赋」而非「前赤壁赋」）、错别字、漏字、多空格
- 正确姿势：先经 1620-4 拿到确切诗名，或用 `poetId` 列出该诗人全部作品再本地匹配
## Why：一个被反复踩的坑
很多开发者第一次用 1620-5 会直觉地传 `title=赤壁赋` 想「搜一下」，结果返回空。文档明确写着 `title` 是「诗词名称（不支持模糊查询）」。这不是 bug，是设计——它做的是精确匹配。理解这点，能省下大量无效调用（也避免白白消耗免费档位）。
## What：参数与接口速览
| 项目 | 说明 |
|------|------|
| 接入点 | 1620-5 名称查询诗词列表 |
| 请求地址 | `https://route.showapi.com/1620-5?appKey={your_appKey}` |
| 入参 | `poetId`（诗人id，选填）、`title`（诗词名称，选填，**精确**）、`page`（页码，默认 1） |
| 返回 | `poemInfo`（Object[]），每项含 `title` / `contentlist` 等 |
| 计费 | 免费（有使用档次限制） |
## How：正确用 title 查诗词
### 步骤 1 · 确认精确诗名
`title` 必须与数据源中的诗名完全一致。例：苏轼的「赤壁」主题有两篇，精确名分别是《前赤壁赋》《后赤壁赋》，传「赤壁赋」查不到。
### 步骤 2 · 精确传入并解析
**Python（requests）**
```python
import requests
APP_KEY = "YOUR_APPKEY"
H = {"content-type": "application/x-www-form-urlencoded"}
def search_by_title(title):
r = requests.post("https://route.showapi.com/1620-5",
params={"appKey": APP_KEY, "title": title, "page": 1},
headers=H, timeout=10)
body = r.json().get("showapi_res_body", {})
if body.get("ret_code") != "0":
raise RuntimeError(body.get("remark"))
return body.get("poemInfo", [])
res = search_by_title("前赤壁赋") # 精确名，可命中
print(len(res), "首匹配")
```
**cURL**
```bash
curl -X POST "https://route.showapi.com/1620-5?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
-d "title=%E5%89%8D%E8%B5%A4%E5%A3%81%E8%B5%8B&page=1"
```
**Node.js（fetch）**
```javascript
const APP_KEY = "YOUR_APPKEY";
const resp = await fetch(`https://route.showapi.com/1620-5?appKey=${APP_KEY}`, {
method: "POST", headers: { "content-type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({ title: "前赤壁赋", page: 1 }),
});
const body = (await resp.json()).showapi_res_body;
console.log(body.ret_code === "0" ? body.poemInfo : body.remark);
```
### 步骤 3 · 查不到时的兜底策略
若 `title` 精确匹配无果，改用 `poetId` 拉取该诗人全部作品（走分页），在本地按关键词 `includes` 模糊筛选——把「模糊」放在你自己的代码里，而不是指望接口。
## 返回示例与解析
精确传入 `title=前赤壁赋`：
```json
{
"showapi_res_body": {
"ret_code": "0",
"remark": "查询成功！",
"poemInfo": [
{ "title": "前赤壁赋", "dynasty": "宋代", "poet": "苏轼",
"contentlist": [ { "original": "壬(rén)戌(xū)之秋……",
"translation": "壬戌年秋……", "annotation": "壬戌：宋神宗元丰五年……" } ] }
],
"maxResult": 20, "allNum": 1, "allPages": 1, "currentPage": 1
}
}
```
若传 `title=赤壁赋`（缺「前」字），`ret_code` 仍可能返回 `"0"` 但 `poemInfo` 为空数组——**空结果不等于失败**，代码要同时判 `ret_code` 与 `poemInfo` 长度。
## 进阶 / 边界
- **空结果 ≠ 失败**：精确名不对时接口常返回 `ret_code="0"` 但 `poemInfo=[]`。务必判断数组长度，别只信 `ret_code`。
- **别称问题**：同一首诗可能有多个流传名称，接口只认数据源里的那一个。需要「别名检索」请本地建别名映射表。
- **poetId 更稳**：若你只关心「某诗人的作品」，直接用 `poetId` 更省心，不必精确拼诗名；再用本地字符串匹配筛选标题。
- **限流考虑**：反复试错式传不同 `title` 会消耗免费档位，建议先用 `poetId` 一次性拉全量再本地匹配。
## FAQ
**Q1：能不能传部分诗名做模糊搜索？**
不能。文档明确「title 不支持模糊查询」，传「赤壁赋」查不到「前赤壁赋」。需要模糊，请改用 `poetId` 拉全量后本地 `includes` 匹配。
**Q2：ret_code 是 0 但 poemInfo 为空，算成功还是失败？**
算「调用成功、但无匹配数据」。接口层面没报错，`remark` 可能仍是「查询成功！」。业务上需把「空数组」当作「未找到」处理。
**Q3：诗名带标点/空格会影响匹配吗？**
会。精确匹配对字符敏感，建议去除首尾空格、保留书名号与否以数据源为准；稳妥做法是先通过 `poetId` 取回真实 `title` 再做精确回查。
**Q4：有没有「搜索框」式的接口？**
当前三个接入点均为精确/条件查询，无全文搜索接入点。搜索体验需由你在本地用拉取的数据自建索引（如倒排或简单字符串匹配）。
## 相关能力 / 下一步阅读
- [唐诗宋词元曲查询返回结构全解：ret_code、dynastyInfo、poemInfo 一文读懂](https://www.showapi.com/guides/poem-response-fields-1620) — 字段与数组结构细节
- [唐诗宋词元曲查询：page 与 maxResult=20 分页翻页拉取全部诗词](https://www.showapi.com/guides/poem-pagination-1620) — 用 poetId 拉全量再本地匹配
- **本系列共 12 篇**：查看[唐诗宋词元曲查询指南总目录](https://www.showapi.com/guides/poem-guides-1620)
