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

快速开始

一次请求拿到 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 可指定任意日期

不传日期则按北京时间取“今天”。若当日无确切日期条目，mode 变为 month，返回该月的高重要度事件。

导出

GET /api/v1/export?format=csv&region=中国 CSV / JSON 全量或筛选结果

CSV 带 UTF-8 BOM，Excel 直接打开不乱码。筛选参数与 /events 一致（不含分页）。

数据结构

字段	类型	说明
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" } }