历史上的今天：date 参数用法（MMDD 格式、默认今天、跨年边界）实战指南
# 历史上的今天：date 参数用法（MMDD 格式、默认今天、跨年边界）实战指南
> 接口：历史上的今天（apiCode=119，接入点 119-42）· 免费 · 请求参数 `date`（可选）· 阅读时间：约 5 分钟
## 核心要点
- `date` 为 **MMDD 四位**格式（如 `0220` 表示 2 月 20 日），文档示例即四位。
- 不传 `date` 时接口默认返回**当前日期**的历史事件。
- 返回里的 `year/month/day` 是事件真实发生的年月日，与 `date` 的月日对应、`year` 各不相同（跨多年）。
## Why：date 用错，查不到想要的
"历史上的今天"本质是"按日期查历史事件"。`date` 控制查哪一天。理解它的格式与默认值，你才能做"每日卡片"（不传 date）或"指定纪念日回顾"（传 date）。
## What：date 参数速览
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `date` | String | 否 | 日期，MMDD 格式（如 `0220`）。不写默认为当前天 |
> 文档仅给出 4 位 MMDD 示例（`0220`）。如需以"年月日"八位等形式传入，以官方文档/调用实测为准，本文不臆造未文档化的格式。
## How：三种用法
### 用法 A：查今天的（做每日卡片，最常用）
不传 `date`：
```bash
curl -X POST "https://route.showapi.com/119-42?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
-d "needContent=0"
```
### 用法 B：查指定日期（如 2 月 20 日）
```python
import requests
url = "https://route.showapi.com/119-42"
params = {"appKey": "YOUR_APPKEY"}
data = {"date": "0220", "needContent": "1"}
resp = requests.post(url, params=params, data=data, timeout=10)
body = resp.json()["showapi_res_body"]
for it in body["list"]:
# 返回的 year 与 date 的月日对应，但年份跨多年
print(it["year"], it["month"], it["day"], it["title"])
```
### 用法 C：前端动态拼接 MMDD（Node.js）
```javascript
function buildDateParam(d = new Date()) {
const mm = String(d.getMonth() + 1).padStart(2, "0");
const dd = String(d.getDate()).padStart(2, "0");
return mm + dd; // 今天的 MMDD
}
const url = `https://route.showapi.com/119-42?appKey=YOUR_APPKEY`;
const body = new URLSearchParams({ date: buildDateParam(), needContent: "1" });
const resp = await fetch(url, { method: "POST", headers: { "content-type": "application/x-www-form-urlencoded" }, body });
console.log(await resp.json());
```
## 返回示例与解析
请求 `date=0220` 返回（节选）：
```json
{
"showapi_res_body": {
"list": [
{ "year": "2008", "month": 2, "day": 20, "title": "2008年2月20日 韩国一军用直升机坠毁造成7人死亡", "img": "http://static1.showapi.com/app2/history_img/3cde348c8e484b5e8b7d708d145be1f3.jpg" },
{ "year": "1960", "month": 2, "day": 20, "title": "1960年2月20日 中国石油大军会战大庆", "img": "" }
],
"ret_code": 0
}
}
```
注意：传入的是月日 `0220`，返回每条的 `year` 不同（2008、1960…），`month/day` 均为 2/20——即"历年 2 月 20 日发生的事"。
## 进阶 / 边界
- **闰年 0229**：2 月 29 日仅在闰年有历史事件，平年查 `0229` 可能返回空 `list`（属正常），前端做好空列表兜底。
- **不传 date = 今天**：服务器按自身时区的"今天"判定，若你面向跨时区用户，建议显式传 `date` 以保证一致性。
- **MMDD 范围**：月份 `01–12`、日 `01–31`；超出合理范围的行为以官方实现为准，不要假设会自动取整。
## FAQ
**Q1：date 能不能传 `20220220` 八位？**
文档示例为 4 位 MMDD（`0220`）。八位等其它格式是否支持以官方文档/实测为准，本文不臆造。
**Q2：不传 date 返回的是哪天？**
返回接口服务器认定的"当前日期"。跨时区部署建议显式传 `date`。
**Q3：返回结果的 `year` 为什么各不相同？**
"历史上的今天"按"月日"聚合历年事件，因此同一次查询里 `month/day` 固定、`year` 跨多年。
**Q4：查某天返回空 list 是正常的吗？**
可能（如平年 0229）。前端需对空列表做友好兜底，而非报错。
## 相关能力 / 下一步阅读
- [历史上的今天：5 分钟接入，从注册到第一条历史事件](https://www.showapi.com/guides/history-today-quickstart-119) — 完整调用骨架。
- [历史上的今天：needContent 参数与图文详情的正确打开方式](https://www.showapi.com/guides/history-today-needcontent-119) — 配合 date 控制返回详略。
- [历史上的今天：网站/App 每日历史卡片组件集成指南](https://www.showapi.com/guides/history-today-widget-119) — 用"不传 date"做每日卡片。
- **本系列共 10 篇**：查看[历史上的今天指南总目录](https://www.showapi.com/guides/history-today-guides-119)
