历史上的今天：5 分钟接入，从注册到第一条历史事件
# 历史上的今天：5 分钟接入，从注册到第一条历史事件
> 接口：历史上的今天（apiCode=119，接入点 119-42）· **免费** · 请求方式 POST/GET · 返回 JSON · 适用人群：新注册用户、初级开发者、教育从业者 · 阅读时间：约 5 分钟
## 核心要点
- 注册并获取 AppKey 后，一个 HTTP 请求就能拿到某天的历史事件列表（`showapi_res_body.list`）。
- 接口只有 2 个**可选**参数（`date`、`needContent`），不传也能跑通（默认查今天）。
- 返回结构稳定：每条事件含 `year/month/day/title`，`needContent=1` 时额外返回 `content` 与 `img`。
## Why：这跟我有什么关系
想在网站侧边栏放一个"历史上的今天"小卡片？想给课堂做每日一史晨读？想给自己的 App 加个趣味开场？这个接口免费、无需复杂参数，几分钟就能接好。它返回的是结构化 JSON，前端怎么排版你说了算。
## What：前置条件与接口速览
| 项目 | 说明 |
|------|------|
| 接口名 | 历史上的今天（apiCode=119） |
| 接入点 | 119-42（仅此 1 个） |
| 接口地址 | `https://route.showapi.com/119-42?appKey={your_appKey}` |
| 请求方式 | POST 或 GET |
| 返回格式 | JSON |
| 计费 | 免费服务（注册后可调用，设防滥用档位，以官方档位说明为准） |
| 鉴权 | AppKey（在 query 参数 `appKey` 中携带） |
| 集成能力 | MCP 服务、OpenAPI 3.0 文档 |
| 更新频率 | 内容持续更新（按"天"维度稳定） |
前置条件：① 注册 ShowAPI 账号；② 在控制台获取 AppKey（https://www.showapi.com/console#/myApp）。
## How：第一次调用
### 步骤 1：拿到 AppKey
登录后进入「我的应用」复制 AppKey，下面代码里替换 `YOUR_APPKEY` 即可运行。
### 步骤 2：发请求（三种语言任选）
**Python（requests）**
```python
import requests
url = "https://route.showapi.com/119-42"
params = {"appKey": "YOUR_APPKEY"}
data = {"date": "0220", "needContent": "1"} # date=MMDD；needContent=1 返回详情
try:
resp = requests.post(url, params=params, data=data, timeout=10)
resp.raise_for_status()
result = resp.json()
if result.get("showapi_res_code") != 0:
print("系统级错误:", result.get("showapi_res_error"))
else:
body = result["showapi_res_body"]
if body.get("ret_code") != 0:
print("业务调用失败 ret_code =", body.get("ret_code"))
else:
for item in body["list"]:
print(f'{item["year"]}年{item["month"]}月{item["day"]}日 -> {item["title"]}')
except requests.RequestException as e:
print("请求异常:", e)
```
**cURL**
```bash
curl -X POST "https://route.showapi.com/119-42?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
-d "date=0220&needContent=1"
```
**Node.js（fetch，内置）**
```javascript
const url = "https://route.showapi.com/119-42?appKey=YOUR_APPKEY";
const body = new URLSearchParams({ date: "0220", needContent: "1" });
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), 10000);
try {
const resp = await fetch(url, {
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded" },
body,
signal: controller.signal,
});
const result = await resp.json();
if (result.showapi_res_code !== 0) {
console.error("系统级错误:", result.showapi_res_error);
} else {
const resBody = result.showapi_res_body;
if (resBody.ret_code !== 0) {
console.error("业务调用失败 ret_code =", resBody.ret_code);
} else {
for (const item of resBody.list) {
console.log(`${item.year}年${item.month}月${item.day}日 -> ${item.title}`);
}
}
}
} catch (e) {
console.error("请求异常:", e.message);
} finally {
clearTimeout(timer);
}
```
### 步骤 3：解析返回
业务数据都在 `showapi_res_body` 内。`ret_code === 0` 表示成功，遍历 `list` 即可拿到每条事件的 `year/month/day/title`（`content`、`img` 在 `needContent=1` 时才有）。
## 返回示例与解析
```json
{
"showapi_res_code": 0,
"showapi_res_error": "",
"showapi_res_id": "6a9527aafb638c3663d5b713",
"showapi_fee_num": 1,
"showapi_res_body": {
"list": [
{
"day": 20,
"title": "2008年2月20日 韩国一军用直升机坠毁造成7人死亡",
"year": "2008",
"month": 2,
"content": "2008年2月20日，韩国国防部确认，一架陆军直升机当天凌晨在京畿道杨平附近山区坠毁，机上7名军人全部死亡。",
"img": "http://static1.showapi.com/app2/history_img/3cde348c8e484b5e8b7d708d145be1f3.jpg"
},
{
"day": 20,
"title": "1960年2月20日 中国石油大军会战大庆",
"year": "1960",
"month": 2,
"content": "1960年2月20日，中央决定开始进行大庆地区石油勘探会战。",
"img": ""
}
],
"ret_code": 0
}
}
```
> 说明：`showapi_fee_num` 为实测响应中出现的系统级调用计数（值 1），非官方文档返回示例显式列出的字段；权威业务数据以 `showapi_res_body` 为准。
## 进阶 / 边界
- **不传 `date`**：默认返回「今天」的历史事件，适合做每日卡片。
- **不传 `needContent`**：默认不返回 `content`/`img`，只给标题列表，最省流量，列表展示足够。
- **免费但有档位限制**：高频调用请参考[本地缓存设计](https://www.showapi.com/guides/history-today-cache-119)。
## FAQ
**Q1：一定要传 `date` 吗？**
不需要。`date` 为可选参数，不传则默认查当前日期。
**Q2：一定要传 `needContent` 吗？**
不需要。不传默认 `0`，只返回标题列表（`title`/`year`/`month`/`day`），不含 `content` 与 `img`。
**Q3：返回里没有 `content` 字段是怎么回事？**
只有 `needContent=1` 时才返回 `content`（及 `img`）。若只要标题列表，这是正常表现。
**Q4：报错 `showapi_res_code` 非 0 是什么情况？**
多为鉴权或系统级问题（如 AppKey 无效），看 `showapi_res_error` 排查。业务层失败看 `showapi_res_body.ret_code`（0 成功 / -1 失败）。
## 相关能力 / 下一步阅读
- [历史上的今天返回字段全解：list / title / year / content / img 一文读懂](https://www.showapi.com/guides/history-today-response-fields-119) — 读懂每个字段与类型坑点。
- [历史上的今天：needContent 参数与图文详情的正确打开方式](https://www.showapi.com/guides/history-today-needcontent-119) — 决定要不要详情内容。
- [历史上的今天：免费接口下如何做本地缓存与更新频率设计？](https://www.showapi.com/guides/history-today-cache-119) — 高频调用省额度。
- **本系列共 10 篇**：查看[历史上的今天指南总目录](https://www.showapi.com/guides/history-today-guides-119)
