# 历史上的今天 · 官方指南总目录
> 接口：历史上的今天（apiCode=119，接入点 119-42）· 生活服务 · 官方自营（昆明秀派科技有限公司）· **免费服务**（注册后默认可免费调用，设防滥用档位）· 请求 POST/GET · 返回 JSON
「历史上的今天」通过 API 查询指定日期发生的国内外大事及政府重要决策，图文并茂、内容持续更新，适合教育、个人兴趣、网站/App 趣味组件等场景。本指南系列从**快速接入 → 参数详解 → 图文处理 → 缓存策略 → 组件集成 → MCP/OpenAPI 生态**分层覆盖，帮你 10 分钟跑通第一个历史查询，并落到生产可用的集成。
## 全系列文章（共 10 篇）
### 入门层
1. [历史上的今天：5 分钟接入，从注册到第一条历史事件](https://www.showapi.com/guides/history-today-quickstart-119) — 注册、拿 AppKey、第一次调用、解析 `list`，附可直接运行的 Python/cURL/Node.js 代码。
2. [历史上的今天返回字段全解：list / title / year / content / img 一文读懂](https://www.showapi.com/guides/history-today-response-fields-119) — 返回体结构对照表 + `ret_code` 取值 + `year` 是字符串的坑点。
### 场景实战层
3. [历史上的今天：date 参数用法（MMDD 格式、默认今天、跨年边界）实战指南](https://www.showapi.com/guides/history-today-date-param-119) — `date=0220` 的 MMDD 规则、不传默认当天、闰年 0229 等边界。
4. [历史上的今天：needContent 参数与图文详情的正确打开方式](https://www.showapi.com/guides/history-today-needcontent-119) — `needContent=1/0` 区别、`content` 与 `img` 的返回条件，按需开启更省。
5. [历史上的今天：教育/课堂场景如何集成历史事件 API？](https://www.showapi.com/guides/history-today-education-119) — 每日一史卡片、课堂晨读组件、延伸阅读数据表设计。
### 技术深挖层
6. [历史上的今天：img 图片字段处理（空字符串、防盗链、懒加载）指南](https://www.showapi.com/guides/history-today-image-handle-119) — `img` 无图返回 `""` 的判断、外链与懒加载兜底。
7. [历史上的今天：免费接口下如何做本地缓存与更新频率设计？](https://www.showapi.com/guides/history-today-cache-119) — 历史数据"按日稳定"带来的缓存红利、以 `date` 为 key 的缓存设计。
### 行业方案层
8. [历史上的今天：网站/App 每日历史卡片组件集成指南](https://www.showapi.com/guides/history-today-widget-119) — 可嵌入的"每日历史"小组件（HTML/CSS/JS），定时拉取、轮播展示。
### 生态集成层
9. [通过 MCP 在 AI 客户端（Cherry Studio / ChatBox）中直接查询历史上的今天](https://www.showapi.com/guides/history-today-mcp-119) — 基于官方 MCP 配置，在 AI 客户端里直接调用。
10. [导入 Postman / Swagger：用 OpenAPI 文档管理历史上的今天接口](https://www.showapi.com/guides/history-today-openapi-119) — 下载 OpenAPI YAML、导入 Postman / Swagger UI、生成请求模板与 Mock。
## 相关资源
| 资源 | 链接 |
|------|------|
| 接口详情页（apiCode=119） | https://www.showapi.com/apiGateway/view/119 |
| 接入点（119-42） | https://www.showapi.com/apiGateway/view/119/42 |
| OpenAPI 文档（YAML） | https://www.showapi.com/openapi/market/119.yaml |
| OpenAPI 文档（JSON） | https://www.showapi.com/openapi/market/119.json |
| AppKey 管理 | https://www.showapi.com/console#/myApp |
| 免费接口档位说明 | https://www.showapi.com/free-api |
## 阅读建议
- **第一次用**：按 1 → 2 → 4 顺序，10 分钟跑通并理解返回。
- **做网站/App 组件**：直接看第 8 篇（组件）＋ 第 7 篇（缓存）。
- **接 AI 工具链**：看第 9 篇（MCP）＋ 第 10 篇（OpenAPI）。
- **教育/内容场景**：看第 5 篇（教育集成）。
