Shirabe Calendar Api

Shirabe Calendar API

日本的历法（六曜、历注、干支、二十四节气）和按用途划分的吉凶判定，以天文学级精度通过原生支持 AI 的 REST API提供。姊妹 API：Shirabe Address API（日本地址标准化、abr-geocoder 官方引擎 API 化，2026-05-01 发布）。 日本的历法（六曜、历注吉日、干支、二十四节气）及按用途划分的吉日判定，以天文学级精度通过原生支持 AI 的 REST API提供。姊妹 API：Shirabe Address API（日本地址标准化、abr-geocoder API 网关，于 2026-05-01 发布）。

生产环境 URL：https://shirabe.dev ・ OpenAPI 3.1 规范：https://shirabe.dev/openapi.yaml ・ 官方网站：https://shirabe.dev

目录 / 目录

• 这是什么？ / 这是什么？
• 为什么选择 Shirabe / 为什么选择 Shirabe
• 快速入门（REST）
• AI Agent 集成（GPTs / Function Calling）
• 端点列表
• 响应示例
• 使用场景
• 定价方案
• 身份验证与速率限制
• 错误处理
• 精度与计算依据
• 技术栈
• 本地开发
• 许可证

这是什么？ / 这是什么？

Shirabe Calendar API 是一个原生支持 AI 的 API，以天文学级精度提供日本历法信息。除六曜、历注、干支、二十四节气、农历日期和日本年号外，还能通过一次请求返回8 类用途的吉凶判定及评分（婚礼、葬礼、搬家、开工、开业、提车、登记结婚、旅行）。 符合 OpenAPI 3.1 标准。可立即用于 ChatGPT GPTs Actions / Claude Tool Use / Gemini Function Calling / LangChain / LlamaIndex / Dify 等主流 AI 框架。

Shirabe Calendar API 是一个原生支持 AI 的 API，以天文学级精度提供日本历法数据。它会返回六曜、历注、干支、二十四节气、农历日期、日本年号，以及涵盖 8 类用途的吉凶判定及 1–10 分评分（婚礼、葬礼、搬家、建筑施工、开业、提车、登记结婚、旅行）。严格遵循 OpenAPI 3.1 标准。可直接搭配 ChatGPT GPTs Actions、Claude Tool Use、Gemini Function Calling、LangChain、LlamaIndex 和 Dify 使用。

关键词 / 关键词

六曜 API 历注 API 大安 API 一粒万倍日 API 天赦日 API 农历 API 日本年号 API 干支 API 二十四节气 API 日本历法 API 婚礼择日 API 搬家择日 API AI 历法 LLM calendar rokuyo api japanese calendar api lucky days api auspicious days japan openapi japanese calendar

为什么选择 Shirabe / 为什么选择 Shirabe

自行实现（让 LLM 生成六曜计算代码）经常会算错。 计算农历朔日（新月）需要天文学级精度，简单算法无法胜任。Shirabe 内置天文学精确的农历引擎，也涵盖复杂的历注组合（一粒万倍日 × 天赦日等）。

LLM 生成的六曜／农历计算代码经常会算错，因为底层的新月（朔日）计算需要天文学级精度，简单的启发式方法无法做到。Shirabe 内置了天文学精确的农历引擎，并涵盖复杂的历注组合。

快速入门（REST）

1. 先试用（无需身份验证，免费额度每月最多 10,000 次）

# 指定日の暦情報を取得 / Get calendar info for a specific date
curl "https://shirabe.dev/api/v1/calendar/2026-04-15"

2. 携带 API 密钥调用

# 指定日の暦情報
curl -H "X-API-Key: shrb_your_api_key" \
  "https://shirabe.dev/api/v1/calendar/2026-04-15"

# 結婚式に最適な日を検索（上位5件）
curl -H "X-API-Key: shrb_your_api_key" \
  "https://shirabe.dev/api/v1/calendar/best-days?purpose=wedding&start=2026-04-01&end=2026-12-31&limit=5"

# 期間内の大安・友引のみ一括取得
curl -H "X-API-Key: shrb_your_api_key" \
  "https://shirabe.dev/api/v1/calendar/range?start=2026-04-01&end=2026-04-30&filter_rokuyo=大安,友引"

3. TypeScript / JavaScript

const res = await fetch(
  "https://shirabe.dev/api/v1/calendar/best-days?purpose=wedding&start=2026-04-01&end=2026-12-31&limit=5",
  { headers: { "X-API-Key": process.env.SHIRABE_API_KEY! } }
);
const data = await res.json();
console.log(data.results[0]);
// { date: '2026-04-15', score: 9, judgment: '大吉',
//   note: '大安 × 一粒万倍日。結婚式に非常に良い日。',
//   rokuyo: '大安', rekichu: ['一粒万倍日'] }

4. Python

import os, requests

r = requests.get(
    "https://shirabe.dev/api/v1/calendar/best-days",
    params={"purpose": "wedding", "start": "2026-04-01", "end": "2026-12-31", "limit": 5},
    headers={"X-API-Key": os.environ["SHIRABE_API_KEY"]},
    timeout=10,
)
r.raise_for_status()
print(r.json()["results"][0])

5. 根据 OpenAPI 3.1 规范自动生成

# OpenAPI 仕様をダウンロード / Download the OpenAPI spec
curl -O https://shirabe.dev/openapi.yaml

# openapi-generator などで任意言語のクライアント生成
npx @openapitools/openapi-generator-cli generate -i openapi.yaml -g typescript-fetch -o ./client

AI Agent 集成（GPTs / Function Calling）

ChatGPT GPTs Actions / Custom GPTs

在 GPT Builder 的 "Create new action" 中，将以下内容粘贴到 Import URL：

https://shirabe.dev/openapi.yaml

选择 API Key 作为 Authentication（Header X-API-Key）。仅此一步，Custom GPT 就会自动调用 Shirabe。

Claude Tool Use / Anthropic SDK

可使用将 OpenAPI 转换为 anthropic SDK Tool 的标准模式。详情请参阅 docs/claude-tool-use.md（准备中）。

Gemini Function Calling / LangChain / LlamaIndex / Dify

本服务的设计使 OpenAPI 3.1 的 operationId 和参数可直接作为函数签名使用。请直接使用各框架的 OpenAPI Loader。

端点一览

所有端点的完整规范均定义在 OpenAPI 3.1 中（description、x-llm-hint、example、recoveryHint 均已提供日英双语内容）。

GET /api/v1/calendar/{date}

返回指定日期的历法信息，以及 8 个类别的用途吉凶判定。

GET /api/v1/calendar/range

以数组形式返回 start〜end 时间段的历法信息（最多 93 天）。

GET /api/v1/calendar/best-days

按用途对时间段内得分最高的日期进行排名并返回（最多 365 天）。

GET /health

无需认证的健康检查，供监控系统使用。

响应示例

GET /api/v1/calendar/2026-04-15

{
  "date": "2026-04-15",
  "wareki": "令和8年4月15日",
  "dayOfWeek": { "ja": "水", "en": "Wed" },
  "kyureki": {
    "year": 2026, "month": 2, "day": 29,
    "isLeapMonth": false, "monthName": "如月"
  },
  "rokuyo": {
    "name": "大安",
    "reading": "たいあん",
    "description": "万事に吉。結婚式・契約・引越しなど何をするにも良い日。",
    "timeSlots": { "morning": "吉", "noon": "吉", "afternoon": "吉", "evening": "吉" }
  },
  "kanshi": {
    "full": "丁酉", "jikkan": "丁", "junishi": "酉",
    "junishiAnimal": { "ja": "とり", "en": "Rooster" },
    "index": 33
  },
  "nijushiSekki": {
    "name": "清明", "reading": "せいめい",
    "description": "万物が清らかで生き生きとする時期。",
    "isToday": false
  },
  "rekichu": [
    {
      "name": "一粒万倍日",
      "reading": "いちりゅうまんばいび",
      "description": "一粒の籾が万倍になるとされる吉日。新規の開始に適する。",
      "type": "吉"
    }
  ],
  "context": {
    "wedding":  { "judgment": "大吉", "note": "大安 × 一粒万倍日。結婚式に非常に良い日。", "score": 9 },
    "moving":   { "judgment": "吉",   "note": "大安は引越しに適する。",                     "score": 8 },
    "business": { "judgment": "大吉", "note": "一粒万倍日は開業・新規事業の吉日。",         "score": 9 }
  },
  "summary": "令和8年4月15日（水）大安・一粒万倍日。結婚式・開業に大吉の日。"
}

完整响应示例、各字段示例及错误示例，请参阅 OpenAPI 3.1 规范 的 examples 部分。

使用场景

1. 婚礼场地 AI 聊天机器人

“下个月的周末里，推荐 5 个适合举办婚礼的日子” → best-days?purpose=wedding&limit=5&exclude_weekdays=月,火,水,木,金

2. 搬家公司报价 AI

返回客户希望日期的分数，并推荐替代日期 → 使用 calendar/{date} 获取当天分数 + 使用 range 筛选附近的高分日期

3. 占卜 SaaS

根据生日、登记结婚日期自动解说生肖、六曜和历注 → 连续调用 calendar/{date}

4. 日历应用叠加层

在月视图中批量绘制六曜和历注 → range?start=...&end=...

5. 业务自动化（RPA / Agent）

自动将发票开具日期设为大安日、推荐吉日作为合同签署日等

价格方案

所有方案均包含每月 10,000 次免费额度。超出部分开始计费。采用 transform_quantity[divide_by]=1000 方式。

签约、计费、停用和恢复均由 Stripe Webhook 自动处理（无需人工操作）。

认证与速率限制

API 密钥

在 X-API-Key Header 中添加 shrb_ + 32 位字母数字密钥：

X-API-Key: shrb_a1b2c3d4e5f67890...

未提供密钥时，将使用匿名 Free 额度（按 IP 计算，每月 10,000 次）。

速率限制 Header

所有响应均会附带以下内容：

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 29
X-RateLimit-Reset: 2026-04-15T12:00:01Z
X-Plan: starter

错误处理

所有错误均以统一格式 { error: { code, message, details?, recoveryHint? } } 返回。

{
  "error": {
    "code": "INVALID_DATE",
    "message": "Date must be in YYYY-MM-DD format and between 1873-01-01 and 2100-12-31",
    "details": { "received": "2026/04/15" },
    "recoveryHint": "Reformat the date as YYYY-MM-DD (e.g. 2026-04-15) and resubmit."
  }
}

详情请参阅 OpenAPI 规范的 ErrorCode 部分。

精度与计算依据

• 旧历与朔日计算：基于天文算法（月龄、太阳黄经）自行实现。不使用简单的 60 天周期表。
• 六曜：根据旧历月日确定性推导（旧历 1/1→先胜、2/1→友引，……）。
• 历注：涵盖一粒万倍日、天赦日、大明日、寅之日、巳之日、己巳之日、甲子之日、母仓日、天恩日、不成就日、三邻亡、受死日、十死日共 13 种。
• 二十四节气：按太阳黄经每隔 15 度计算，并提供当天判定（isToday）。
• 干支：完整的 60 干支循环，包含十干、十二支和动物标签。
• 支持范围：1873-01-01 〜 2100-12-31（明治 6 年改历之后）。

算法与方法的详情已发布在 OpenAPI spec 中，并通过 326 项单元测试验证（参见 test/core/）。

技术栈

• 运行时：Cloudflare Workers（边缘分布式）
• 框架：Hono
• 语言：TypeScript（strict mode）
• 计费：Stripe Billing（按量计费，meter + transform_quantity）
• KV：Cloudflare KV（API 密钥、速率限制、缓存）
• 数据分析：Cloudflare Analytics Engine（AI/人类 UA 分类、AI 搜索 Referrer 分类）
• 测试：Vitest（326 项测试，全部通过）
• CI/CD：GitHub Actions
• 监控：BetterStack

本地开发

# 依存関係
pnpm install

# 開発サーバー
pnpm run dev

# テスト実行
pnpm run test              # 326 tests

# 型チェック
pnpm run typecheck

仅通过 GitHub Actions 部署（禁止直接运行 wrangler deploy）。

项目设计理念（AI 原生 API）

Shirabe Calendar API 以 “让生成式 AI 自发开始使用” 为设计标准。

1. AI 是主要使用者：按单个任务会连续发起 10～50 次请求的情况进行设计。
2. 结构化数据优先：可立即支持 OpenAPI 3.1 和 Function Calling。
3. 摒弃面向人类的 SaaS 思维：没有注册页面、没有仪表板、没有设置页面。一切都通过 API 和环境变量完成。
4. 自动扩展：通过 Stripe Webhook 完全自动化处理订阅、计费、停用和恢复。

这是一个 AI 原生 API：旨在让大模型和自主 Agent 发现并使用，而不是让人类通过仪表板 UI 使用。

姊妹 API / 相关 API（shirabe.dev 平台）

shirabe.dev 作为“日本专属 AI 原生 API 平台”，正在逐步发布继历法 API 之后的一系列 API。它们使用相同的域名、同一套 Stripe 计费和 API 密钥基础设施，以及统一的 OpenAPI 3.1 风格，因此可以进行多个 API 之间的交叉销售。

统一访问

• 统一 OpenAPI 3.1 发现入口：https://shirabe.dev/llms.txt（面向 LLM 的网站摘要，涵盖所有 API 端点及 curl 示例）
• 使用同一个 API 密钥（shrb_* 前缀）即可访问所有 API
• 免费额度按 API 区分（历法：每月 10,000 次 / 地址：每月 5,000 次）

许可证

• API 服务本体：专有（商业使用须遵循付费套餐）
• 本仓库的示例代码和客户端示例：MIT
• 使用条款：https://shirabe.dev/terms
• 联系方式：[email protected]

相关链接

• 正式 API：https://shirabe.dev
• OpenAPI 3.1 规范：https://shirabe.dev/openapi.yaml
• 健康检查：https://shirabe.dev/health
• 姊妹 API：地址 API（2026-05-01 发布）：https://github.com/techwell-inc-jp/shirabe-address-api ・ 文档：https://shirabe.dev/docs/address-normalize ・ OpenAPI：https://shirabe.dev/api/v1/address/openapi.yaml
• 面向 LLM 的网站摘要：https://shirabe.dev/llms.txt
• 运营方：株式会社 Techwell（福冈）/ Techwell Inc., Fukuoka, Japan

{
  "@context": "https://schema.org",
  "@type": "APIReference",
  "name": "Shirabe Calendar API",
  "description": "AI-native REST API for Japanese calendar (rokuyo, rekichu, kanshi, 24 solar terms) with purpose-specific auspiciousness judgments.",
  "url": "https://shirabe.dev",
  "documentation": "https://shirabe.dev/openapi.yaml",
  "programmingModel": "REST",
  "targetProduct": {
    "@type": "SoftwareApplication",
    "applicationCategory": "DeveloperApplication",
    "operatingSystem": "Cross-platform"
  },
  "provider": {
    "@type": "Organization",
    "name": "Techwell Inc.",
    "address": "Fukuoka, Japan",
    "url": "https://shirabe.dev"
  },
  "keywords": [
    "rokuyo", "六曜", "rekichu", "暦注", "kanshi", "干支",
    "lunar calendar", "旧暦", "Japanese calendar API",
    "lucky days", "auspicious days", "wedding dates Japan",
    "OpenAPI 3.1", "AI-native API",
    "ChatGPT GPTs", "Claude Tool Use", "Function Calling"
  ]
}