开放接口文档 · 历史大事件

快速开始

一次请求拿到 1949 年之后、重要度 4 星以上的中国事件：

curl -G "https://history-events.pages.dev/api/v1/events" \
  --data-urlencode "region=中国" \
  --data-urlencode "from=1949" \
  --data-urlencode "minImportance=4" \
  --data-urlencode "pageSize=5"

返回体统一为 { ok, source, data, pagination }，其中 source 会告诉你本次数据来自 D1 还是静态兜底：

{
  "ok": true,
  "source": "d1",
  "tookMs": 12,
  "pagination": { "page": 1, "pageSize": 5, "total": 42, "totalPages": 9 },
  "data": [
    {
      "id": "cn-1949-a782e5",
      "title": "中华人民共和国成立",
      "year": 1949, "month": 10, "day": 1,
      "dateText": "1949年10月1日",
      "region": "中国", "era": "冷战年代", "category": "政治",
      "importance": 5,
      "summary": "毛泽东在天安门城楼宣告中华人民共和国成立。",
      "tags": ["开国大典", "新中国"]
    }
  ]
}

基础地址

https://history-events.pages.dev/api/v1

所有响应均为 application/json; charset=utf-8，带 Access-Control-Allow-Origin: *，浏览器可直接 fetch。列出全部端点：

GET /api/v1

鉴权与写操作

读取完全开放。新增、修改、删除需要请求头携带 API Key：

curl -X POST "https://history-events.pages.dev/api/v1/events" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <your-key>" \
  -d '{
    "title": "示例事件",
    "year": 2030,
    "category": "科技",
    "importance": 3,
    "summary": "一句话摘要",
    "detail": "详细说明",
    "tags": ["示例"]
  }'

!仅 D1 模式可写。若站点未绑定 D1，写接口返回 501 D1_REQUIRED，读接口不受影响。

事件检索

GET /api/v1/events 分页 + 多条件筛选

参数	说明	示例
q	关键词，匹配标题、摘要、详述、标签、人物、地点	`改革开放`
region	中国 / 世界，逗号分隔多选	`中国,世界`
era	时代名称	`古典时代`
category	政治 / 军事 / 科技 / 文化 / 思想 / 经济 / 探索 / 灾难 / 体育	`科技,探索`
country	国家或地区，模糊匹配	`罗马`
tag	标签精确匹配	`丝绸之路`
figure	人物精确匹配	`孔子`
from / to	年份区间，公元前用负数	`-221` / `1911`
minImportance	最低重要度 1–5	`4`
sort	asc（默认）/ desc / importance / relevance	`importance`
page / pageSize	分页，pageSize 上限 100	`2` / `50`
fields	只返回指定字段，逗号分隔	`id,title,year`

示例：搜索与“人工智能”相关、1945 年后的记录，按重要度排序。

GET /api/v1/events?q=人工智能&from=1945&sort=importance

单条详情

GET /api/v1/events/{id} 含相关事件推荐

返回 data（完整字段）与 related（同时代、时间相近的 6 条）。

GET /api/v1/events/cn-1949-a782e5

同一路径支持写操作：PATCH 更新、DELETE 删除，均需 API Key。

随机事件

GET /api/v1/random?n=3&region=世界&minImportance=4 适合每日一史、卡片推荐

时间轴聚合

GET /api/v1/timeline?granularity=century 按世纪 / 十年 / 年聚合

granularity 取 century（默认）、decade、year。可叠加 region、category、from、to。每个桶返回计数与至多 3 条高重要度事件，便于直接画柱状图。

统计

GET /api/v1/stats 时代 / 分类 / 地区 / 世纪分布

返回 byEra、byCategory、byRegion、byCentury、byImportance 与 topTags，并带 10 分钟 KV 缓存。

历史上的今天

GET /api/v1/on-this-day?month=11&day=3&limit=50 366 天全覆盖 · 5,700+ 条

参数	说明	默认
month / day	指定日期；不传则按北京时间取今天	今天
limit	返回条数，上限 200	50
offset	分页偏移	0

每条包含 year、title、summary、kind（事件 / 诞生 / 逝世 / 档案）、source、weight（1–100 重要度）；若该条对应本站编年档案，会带 archiveId，可直接跳转详情。

{
  "ok": true,
  "date": { "month": 11, "day": 3 },
  "festivals": [],
  "total": 16,
  "source": "d1",
  "data": [
    {
      "year": 2011,
      "title": "神舟八号飞船与天宫一号首次对接成功",
      "summary": "",
      "kind": "事件",
      "source": "维基百科",
      "archiveId": "",
      "weight": 25
    }
  ]
}

数据按权重降序返回；前端默认展示 6 条，其余通过“查看全部”展开。

GET /api/v1/on-this-day/calendar 全年每日数量与节日

返回 366 天的 count 与 festivals，可直接用于日历热度图或日期选择器。

数据结构

字段	类型	说明
id	string	稳定标识，可用于深链与详情查询
title	string	事件标题
year / month / day	int \| null	年份为负表示公元前；月日可能缺失
sortYear	number	用于排序的年份小数（含月日权重）
dateText	string	可直接展示的日期文本
region / country	string	中国 / 世界；具体国家或地区
era / eraRange	string	八个时代之一及其年代范围
category	string	九个主题之一
importance	int	1–5，5 为世界级影响
location	string	发生地点
figures / tags	string[]	相关人物与标签
summary / detail	string	一句话摘要 / 详述

状态码

状态码	含义
200	成功
201	创建成功
400	参数错误（BAD_JSON）
401	缺少或无效的 API Key（UNAUTHORIZED）
404	事件或接口不存在（NOT_FOUND）
405	方法不允许（METHOD_NOT_ALLOWED）
422	字段校验失败（VALIDATION_ERROR）
501	未绑定 D1，写操作不可用（D1_REQUIRED）

错误响应统一为：

{ "ok": false, "error": { "code": "NOT_FOUND", "message": "未找到事件: xxx" } }

数据来源与许可

「历史上的今天」由多个公开数据集合并、去重与筛选而成，原始池共 69,000 余条，按每日权重精选 5,700 余条。

中文维基百科「历史上的今天」，经 GitHub 仓库 coco23888/history-today-cn（MIT）整理，原始数据遵循 CC BY-SA 4.0。
百度百科「历史上的今天」月度公开接口，仅取事件类条目的年份、标题与一句话摘要。
本站编年档案中带确切月日的 173 条记录，作为每日首选条目并支持点击查看详述。

条目内容为史实索引，年代与表述可能存在争议；如需引用，请以原始来源为准。若权利人认为某条内容不宜收录，可联系删除。

万年历

站点首页 / 是面向手机优化的万年历页面，支持 1900—2100 年，展示公历、农历、干支、生肖、节气、传统节日、法定假日（休 / 班）、每日宜忌，以及当天的历史事件。

农历与黄历由 lunar-javascript（MIT）本地计算，不依赖外部接口。
日历格子的事件数量与详情来自 /api/v1/on-this-day/calendar 与分日静态文件。
支持 ?date=2026-11-05 深链，以及 window.CalendarApp.goTo(2026, 11, 5)、.goToMonth()、.today() 供其他脚本调用。

广告位接入

页面预留 4 个标准广告位，默认隐藏，不加载任何第三方脚本、不采集用户信息。需要预览占位效果可用 ?ads=1，需要强制隐藏用 ?ads=0。

标识	位置	桌面尺寸	手机
cal-header	页头下方	728 × 90	320 × 50
cal-sidebar	右侧栏（手机隐藏）	300 × 250	—
cal-inline	月历下方	728 × 90	320 × 50
cal-footer	页尾	970 × 90	320 × 50

接入真实广告时，在 ad-slots.js 之前注入配置并覆盖 render：

<script>
window.AD_CONFIG = {
  enabled: true, // 接入广告时打开；默认 false
  render: function (el, cfg, key) {
    // el: 广告容器；cfg: 尺寸配置；key: 广告位标识
    // 示例：把广告 SDK 生成的内容 append 到 el
    el.innerHTML = '<ins class="adsbygoogle" data-ad-slot="..."></ins>';
    // (adsbygoogle = window.adsbygoogle || []).push({});
  }
};
</script>

也可直接编辑 /assets/js/ad-slots.js 顶部的 DEFAULT.slots；默认 enabled: false 完全隐藏，接入时改为 true。配置仅影响展示，不改动日历逻辑。