营销日历CALENDATAFullsite Markdown

接口文档

把营销日历，接入你的应用。

标准 JSON 接口，支持日期、分类与关键词筛选。
注册领取免费 Key，即可查询本月全部事件。

领取免费 API Key浏览接口 ↓
快速开始

两步完成接入

1

领取访问密钥

登录个人中心，领取专属 API Key。完整密钥仅在领取或重置时显示，请及时保存。

前往个人中心 →
2

添加请求头

将 Key 放入 X-API-Key 请求头。不要放进网址或公开网页代码。

每日 100 次每分钟 10 次本月免费


在线调试
试一次查询
每次成功查询消耗 1 次额度，查看用量不消耗额度。密钥只用于当前请求，不会保存在浏览器。
请求结果会显示在这里。


标题中的“历史纪念”表示往年发生的事件，不代表本年度活动安排。所选月份暂未更新时返回 404，不扣额度。
下面的响应示例用于说明结构，日期、数量与额度以实际返回为准。
接口一览
点击接口，查看详细文档。
请求地址：https://calendata.date
GET/api/v1/events查询事件列表
需要 API Key · 每次成功查询消耗 1 次额度
请求参数
字段填写方式说明
start_date可选 · YYYY-MM-DD开始日期，默认为本月第一天
end_date可选 · YYYY-MM-DD结束日期，默认为本月最后一天
category_id可选 · 正整数按分类编号筛选，可通过分类接口获取
q可选 · 最多 100 个字符按事件名称搜索
page可选 · 1–10000页码，默认 1
page_size可选 · 1–200每页条数，默认 50
请求示例
curl 'https://calendata.date/api/v1/events' \
  -H 'X-API-Key: YOUR_API_KEY'
响应示例
{
  "total": 1,
  "page": 1,
  "page_size": 50,
  "has_more": false,
  "missing_months": [],
  "items": [
    {
      "id": "e7f9d55b17d64a81a87fc3a83a97f07ab12b4478",
      "title": "国庆节",
      "date": "2026-10-01",
      "category_id": 4,
      "description": "",
      "category": "公历"
    }
  ]
}
返回说明
免费账户可查询北京时间本月范围内的事件，开始日期不能晚于结束日期。
字段说明
total符合条件的事件总数
page / page_size当前页码与每页条数
has_more是否还有下一页
missing_months暂未更新的月份；空数组表示所查询月份可用
items事件列表，未匹配到事件时为空数组
字段类型说明
idstring事件编号，可用于查询事件详情
titlestring事件名称
datestring日期，格式 YYYY-MM-DD
category_idinteger分类编号
categorystring分类名称
descriptionstring事件说明，暂无说明时为空字符串
GET/api/v1/events/{id}查询事件详情
需要 API Key · 每次成功查询消耗 1 次额度
请求参数
字段填写方式说明
id必填 · 路径参数从事件列表中的 id 字段获取
请求示例
curl 'https://calendata.date/api/v1/events/e7f9d55b17d64a81a87fc3a83a97f07ab12b4478' \
  -H 'X-API-Key: YOUR_API_KEY'
响应示例
{
  "id": "e7f9d55b17d64a81a87fc3a83a97f07ab12b4478",
  "title": "国庆节",
  "date": "2026-10-01",
  "category_id": 4,
  "description": "",
  "category": "公历"
}
返回说明
字段类型说明
idstring事件编号，可用于查询事件详情
titlestring事件名称
datestring日期，格式 YYYY-MM-DD
category_idinteger分类编号
categorystring分类名称
descriptionstring事件说明，暂无说明时为空字符串
仅可查询本月的事件。编号不存在返回 404，日期超出范围返回 403。
GET/api/v1/categories获取事件分类
需要 API Key · 不消耗查询额度
请求参数
不需要填写查询参数。
请求示例
curl 'https://calendata.date/api/v1/categories' \
  -H 'X-API-Key: YOUR_API_KEY'
响应示例
[
  {
    "id": 3,
    "name": "农历"
  },
  {
    "id": 4,
    "name": "公历"
  }
]
返回说明
返回分类列表，包含分类编号 id 和分类名称 name。列表可能更新，请以实际响应为准。
GET/api/v1/usage查看调用额度
需要 API Key · 不消耗查询额度
请求参数
不需要填写查询参数。
请求示例
curl 'https://calendata.date/api/v1/usage' \
  -H 'X-API-Key: YOUR_API_KEY'
响应示例
{
  "name": "我的应用",
  "expires_at": "2027-10-01T00:00:00",
  "limit": 100,
  "used": 1,
  "remaining": 99,
  "window": "day",
  "total_requests": 1,
  "plan": "free",
  "daily_limit": 100,
  "daily_used": 1,
  "daily_remaining": 99,
  "minute_limit": 10,
  "minute_used": 1,
  "minute_remaining": 9
}
返回说明
字段说明
expires_atKey 有效期，UTC 时间
limit / used / remaining当前额度上限、已用次数、剩余次数
windowday 表示按日计算
total_requests累计成功调用次数
plan当前账户套餐，免费为 free
daily_* / minute_*日与分钟额度、用量及剩余次数
GET/api/v1/calendar获取本月日历
需要 API Key · 每次成功查询消耗 1 次额度
请求参数
字段填写方式说明
year可选 · 1901–2099年份，与月份一起指定；默认本年
month可选 · 1–12月份；默认本月，仅允许本月
请求示例
curl 'https://calendata.date/api/v1/calendar' \
  -H 'X-API-Key: YOUR_API_KEY'
响应示例
{
  "year": 2026,
  "month": 10,
  "total": 1,
  "shown": 1,
  "locked": false,
  "items": [
    {
      "id": "e7f9d55b17d64a81a87fc3a83a97f07ab12b4478",
      "title": "国庆节",
      "date": "2026-10-01",
      "category_id": 4,
      "description": "",
      "category": "公历"
    }
  ]
}
返回说明
仅返回本月完整事件列表；次月、历史和其他未来月份均返回 403，不返回事件或数量。shown 为实际返回事件数。
GET/api/v1/meta获取日历配置
需要 API Key · 不消耗查询额度
请求参数
不需要填写查询参数。
请求示例
curl 'https://calendata.date/api/v1/meta' \
  -H 'X-API-Key: YOUR_API_KEY'
响应示例
{
  "years": [
    2026
  ],
  "total": 195,
  "categories": [
    {
      "id": 4,
      "name": "公历"
    }
  ],
  "months": [
    {
      "month": "2026-10",
      "count": 195,
      "locked": false,
      "available": true
    },
    {
      "month": "2026-11",
      "locked": true
    }
  ],
  "current_month": "2026-10",
  "next_month": "2026-11",
  "free_start_date": "2026-10-01",
  "free_end_date": "2026-10-31",
  "free_daily_limit": 100,
  "free_minute_limit": 10,
  "contact_text": "",
  "contact_url": ""
}
返回说明
返回可选年份、分类、本月查询范围和免费额度。次月仅标记月份与订阅状态，不返回数量或可用性。available 表示月份内容是否可用，locked 表示事件内容是否需要订阅。日期范围随北京时间每月自动切换。


额度与错误处理
列表、详情和本月日历共用额度；成功的空查询也消耗 1 次。错误请求不消耗查询额度。日额度在北京时间零点重置，不累计到下一天。
响应头含义
X-RateLimit-Limit今日额度上限
X-RateLimit-Remaining今日剩余次数
X-RateLimit-Reset下次重置时间（UTC，ISO 8601 格式）
X-MinuteLimit-Remaining当前分钟剩余次数
Retry-After超限后建议等待的秒数
状态码原因处理建议
401Key 缺失、无效或停用检查请求头；重置后请使用新 Key
403Key 到期或查询日期超出范围检查有效期，并将日期设为本月
404事件不存在或月份暂未更新检查事件编号，或稍后重试
422参数格式或范围不正确按照接口参数说明调整
429调用过于频繁或额度已用完按 Retry-After 等待后重试
503服务暂时不可用稍后重试
{
  "detail": "请提供有效的 X-API-Key"
}
次月、历史和全年 API 查询暂未开放。次月网页内容订阅后查看，订阅即将开放。