MARKETING CALENDAR / API
你的应用，也有好时机。
用一个简单的请求，免费获取本月营销事件。
支持日期范围、分类筛选、关键词与分页。
01. 获取 API Key
联系站长免费申请 Key。每人先开通一个，每天 100 次、每分钟 10 次，北京时间零点重置。
联系站长免费申请 API Key
已有 Key？可在右侧直接测试，或返回日历页查看本月全部事件。Key 仅在当前页面内存中使用，刷新即清除。
02. 发起请求
GET/api/v1/events
打开交互式接口文档 ↗在线试一试
填入免费 Key 查询本月数据，每次成功查询扣除 1 次今日额度。
响应会显示在这里。
接口一览
| 接口 | 用途 | 调用规则 |
|---|---|---|
| GET /api/v1/events | 查询本月事件，支持日期、分类、关键词与分页 | 需要 Key，成功扣 1 次 |
| GET /api/v1/events/{id} | 查看本月单条事件及数据来源 | 需要 Key，成功扣 1 次 |
| GET /api/v1/categories | 获取分类编号与名称 | 需要 Key，不扣额度 |
| GET /api/v1/usage | 查看有效期、今日用量与剩余额度 | 需要 Key，不扣额度 |
| GET /api/public/preview | 本月固定少量样本 | 无需 Key |
查询规则
范围明确，返回稳定
仅限北京时间本月，不填日期默认查询本月。每页默认 50 条、最多 200 条，可按分类和关键词查询。
免费额度
用多少，看得见
每天 100 次、每分钟 10 次；北京时间零点重置，不累计到下一天。列表与详情共用额度，成功空查询也扣次数，错误不扣。超限返回 429。
数据说明
保留来源，不猜日期
日期换算标注 date_basis，采集时间为 UTC。missing_months 表示未采集月份；没有收录的活动不会自动补全。
后续付费功能
历史月份、未来月份、跨月与全年查询，后续按套餐开放。当前免费试用阶段，不提供购买或充值入口。
常见状态码
401：Key 缺失、无效或停用；403：Key 到期或日期超出免费范围；404：事件或示例月份未收录；422：参数错误；429：额度不足；503：数据库暂不可用。完整 API 响应标记为不可共享缓存。
源站记录未经逐条人工核验；公历月日记录按来源规则展开到对应年份，origin_year 是事件起始年份，不是本次举办年份。影视、展会等历史记录不代表当年重新举办。节气由 lunar-python 计算。