唐诗宋词元曲查询：5 分钟从注册到查出第一个朝代列表
# 唐诗宋词元曲查询：5 分钟从注册到查出第一个朝代列表
> 接口：唐诗宋词元曲等诗词查询（apiCode=1620）· 免费 · 请求方式 POST/GET · 返回 JSON · 适用：新注册用户、初级开发者、国风爱好者 · 阅读约 5 分钟
## 核心要点
- 注册 ShowAPI 账号并创建应用，拿到 `appKey` 即可调用，接口**免费**（有使用档次限制）
- 第一个调用选「查询朝代列表」（1620-3），它**无需任何业务参数**，最适合验证连通性
- 返回数据统一包在 `showapi_res_body` 中，`ret_code` 为 `"0"` 表示成功
## Why：这跟你有什么关系
想给网站、小程序或课堂作业加一点「国风」？比如做一个诗人介绍页、一首诗词的赏析卡片，或者一个随机推诗的小组件——你不需要自己建诗词数据库。ShowAPI 的「唐诗宋词元曲查询」已经把唐诗、宋词、元曲整理好了，注册就能免费调。
本篇目标很简单：**5 分钟内完成第一次成功调用**，看到返回的朝代列表。这一步跑通，后面的诗人查询、诗词查询都是同一套套路。
## What：前置条件与接口速览
| 项目 | 说明 |
|------|------|
| 接口名称 | 唐诗宋词元曲等诗词查询 |
| 接口编码 | 1620 |
| 本篇接入点 | 查询朝代列表（1620-3） |
| 请求地址 | `https://route.showapi.com/1620-3?appKey={your_appKey}` |
| 请求方式 | POST / GET |
| 鉴权方式 | `appKey` 作为 URL 查询参数（也可用请求头，详见各接入点示例） |
| 返回格式 | JSON，业务数据在 `showapi_res_body` 内 |
| 计费 | 免费（注册默认可调用，有使用档次限制） |
前置条件：一个 ShowAPI 账号 + 一个已创建的 Application（拿到 `appKey`）。在 [AppKey 管理页](https://www.showapi.com/console#/myApp) 获取。
## How：四步跑通第一次调用
### 步骤 1 · 注册并获取 AppKey
登录 ShowAPI → 进入「我的应用」创建一个应用 → 复制该应用的 `appKey`（一串字母数字）。下文用 `YOUR_APPKEY` 占位，请替换成你自己的。
### 步骤 2 · 发起第一次请求（查询朝代列表）
查询朝代列表**不需要任何业务参数**，只要带上 `appKey`。下面给出三种语言的可运行示例。
**Python（requests）**
```python
import requests
APP_KEY = "YOUR_APPKEY"
URL = "https://route.showapi.com/1620-3"
try:
r = requests.post(
URL,
params={"appKey": APP_KEY},
headers={"content-type": "application/x-www-form-urlencoded"},
timeout=10,
)
r.raise_for_status()
data = r.json()
body = data.get("showapi_res_body", {})
if body.get("ret_code") != "0":
print("调用失败：", body.get("remark"))
else:
for d in body.get("dynastyInfo", []):
print(d["dynasty"], d["dynastyId"])
except requests.RequestException as e:
print("请求异常：", e)
```
**cURL**
```bash
curl -X POST "https://route.showapi.com/1620-3?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded"
```
**Node.js（fetch）**
```javascript
const APP_KEY = "YOUR_APPKEY";
const URL = "https://route.showapi.com/1620-3";
try {
const resp = await fetch(`${URL}?appKey=${APP_KEY}`, {
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded" },
});
const data = await resp.json();
const body = data.showapi_res_body || {};
if (body.ret_code !== "0") {
console.log("调用失败：", body.remark);
} else {
for (const d of body.dynastyInfo || []) {
console.log(d.dynasty, d.dynastyId);
}
}
} catch (e) {
console.log("请求异常：", e.message);
}
```
### 步骤 3 · 解析返回
成功时 `showapi_res_body.ret_code` 为 `"0"`，`dynastyInfo` 是一个数组，每项含 `dynasty`（朝代名）与 `dynastyId`（朝代唯一 ID）。`dynastyId` 很关键——下一步查诗人时要用它。
### 步骤 4 · 展示结果
拿到数组后直接渲染即可。例如前端用 `dynastyInfo.map(d => <li>{d.dynasty}</li>)` 列出所有朝代；点某个朝代时把它对应的 `dynastyId` 传给「人名或朝代查询诗人」接口，就能继续往下查诗人。
## 返回示例与解析
```json
{
"showapi_res_code": 0,
"showapi_res_error": "",
"showapi_res_id": "ce135f6739294c63be0c021b76b6fbff",
"showapi_res_body": {
"ret_code": "0",
"remark": "查询成功!",
"dynastyInfo": [
{ "dynastyId": "5b1de348cbf6a77b365977e5", "dynasty": "宋代" },
{ "dynastyId": "5b1de349cbf6a77b365977e8", "dynasty": "唐代" },
{ "dynastyId": "5b1de34ecbf6a77b365977ed", "dynasty": "南北朝" }
]
}
}
```
| 字段 | 类型 | 说明 |
|------|------|------|
| `showapi_res_body.ret_code` | String | `"0"` 成功，其他为失败 |
| `showapi_res_body.remark` | String | 提示信息，如「查询成功!」 |
| `showapi_res_body.dynastyInfo` | Object[] | 朝代列表 |
| `dynastyInfo[].dynasty` | String | 朝代名称 |
| `dynastyInfo[].dynastyId` | String | 朝代 ID，下游查询诗人时作为入参 |
## 进阶 / 边界
- **免费但有档次限制**：接口注册后默认可免费调用，系统为防滥用设有使用档次（积分）限制。高频或批量调用前请先了解档位，必要时做本地缓存（详见《免费也有档次限制，如何用本地缓存避免触发限流？》）。
- **没有业务参数不等于没有鉴权**：1620-3 虽无业务入参，但 `appKey` 必填，否则无法区分调用方与计费/限流归属。
- **`ret_code` 是字符串不是数字**：注意文档中 `ret_code` 的值是字符串 `"0"`，判断时用 `== "0"` 而非 `== 0`。
## FAQ
**Q1：调用返回 ret_code 不是 "0" 怎么办？**
先看 `remark` 字段的提示信息。`ret_code` 非 `"0"` 通常表示参数或权限问题；若 `showapi_res_body` 缺失，检查 `appKey` 是否正确、是否带了 `content-type` 头。
**Q2：接口真的是免费的吗？会不会偷偷扣费？**
文档明确标注为「免费」，注册后默认可调用，仅设有防止滥用的使用档次限制。具体档位与积分说明见官方免费 API 页面，不存在按次扣费。
**Q3：GET 和 POST 都能用吗？**
能。文档标注请求方式为 POST/GET，两种均可；示例中以 POST + `application/x-www-form-urlencoded` 为主。
**Q4：appKey 能写在前端代码里吗？**
不建议。`appKey` 关联你的账号与调用额度，暴露在公网前端有被滥刷、触发限流的风险。浏览器端调用建议走你自己的后端代理，由后端持有 `appKey`。
## 相关能力 / 下一步阅读
- [唐诗宋词元曲查询返回结构全解：ret_code、dynastyInfo、poemInfo 一文读懂](https://www.showapi.com/guides/poem-response-fields-1620) — 读懂三个接入点的全部字段
- [唐诗宋词元曲查询：从「朝代」到「诗人」到「诗词」三步全链路串联](https://www.showapi.com/guides/poem-three-step-flow-1620) — 用 dynastyId 继续往下查诗人、查诗词
- **本系列共 12 篇**：查看[唐诗宋词元曲查询指南总目录](https://www.showapi.com/guides/poem-guides-1620)
