Shirabe Calendar API

Japan's calendar (rokuyo, rekichu auspicious days, kanshi, 24 solar terms) and purpose-specific auspicious-day judgments, served with astronomical precision as an AI-native REST API + MCP server.

Production URL: https://shirabe.dev ・ OpenAPI 3.1 Spec: https://shirabe.dev/openapi.yaml ・ MCP: https://shirabe.dev/mcp ・ Official Site: https://shirabe.dev

Table of Contents

• What is this?

• Why Shirabe

• Quick Start (REST)

• AI Agent Integration (MCP / GPTs / Function Calling)

• Endpoints

• Response Example

• Use Cases

• Pricing Plans

• Authentication and Rate Limiting

• Error Handling

• Precision and Methodology

• Tech Stack

• Local Development

• License

Related MCP server: Edition Intelligence Platform

What is this?

Shirabe Calendar API is an AI-native API serving Japanese calendar data with astronomical precision. It returns rokuyo, rekichu, kanshi, 24 solar terms, lunar date, Japanese era, plus purpose-specific auspiciousness judgments with 1–10 scores across 8 categories (wedding, funeral, moving, construction, business, car delivery, marriage registration, travel) in a single request. Strict OpenAPI 3.1. Works out-of-the-box with ChatGPT GPTs Actions, Claude Tool Use, Gemini Function Calling, LangChain, LlamaIndex, and Dify.

Keywords

rokuyo api rekichu api taian api ichiryumanbai-bi api tensha-bi api lunar calendar api japanese era api kanshi api 24 solar terms api japan calendar api wedding date api moving date api AI calendar LLM calendar rokuyo api japanese calendar api lucky days api auspicious days japan mcp server japan openapi japanese calendar

Why Shirabe

LLM-generated rokuyo/lunar calculation code is known to miscalculate because the underlying new-moon (saku) computation requires astronomical precision that simple heuristics fail to capture. Shirabe ships an astronomically accurate lunar engine and covers complex rekichu combinations (e.g., Ichiryumanbai-bi × Tensha-bi).

Quick Start (REST)

1. Try it out (No auth, Free tier up to 10,000 req/month)

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

2. Call with API Key

# 指定日の暦情報
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. Auto-generate from OpenAPI 3.1 Spec

# 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 Integration (MCP / GPTs / Function Calling)

Model Context Protocol (MCP)

Simply add the following to your claude_desktop_config.json to use it directly from Claude Desktop:

{
  "mcpServers": {
    "shirabe-calendar": {
      "command": "npx",
      "args": ["-y", "@shirabe-api/calendar-mcp"],
      "env": { "SHIRABE_API_KEY": "shrb_your_api_key" }
    }
  }
}

Streamable HTTP-compatible clients can also point directly to the URL:

{
  "mcpServers": {
    "shirabe-calendar": { "url": "https://shirabe.dev/mcp" }
  }
}

Available MCP Tools

ChatGPT GPTs Actions / Custom GPTs

In GPT Builder, select "Create new action" and paste the following into the Import URL:

https://shirabe.dev/openapi.yaml

For Authentication, select API Key (Header X-API-Key). Your custom GPT will now automatically call Shirabe.

Claude Tool Use / Anthropic SDK

Works using the standard pattern for converting OpenAPI to anthropic SDK tools. See docs/claude-tool-use.md (in preparation) for details.

Gemini Function Calling / LangChain / LlamaIndex / Dify

Designed so that the OpenAPI 3.1 operationId and parameters map directly to function signatures. Use the OpenAPI Loader provided by each framework.

Endpoints

The full specification for all endpoints is defined in the OpenAPI 3.1 file (including descriptions, x-llm-hint, examples, and recoveryHint in both Japanese and English).

GET /api/v1/calendar/{date}

Returns calendar info and 8-category auspiciousness scores for a single day.

GET /api/v1/calendar/range

Returns an array of calendar info for a range from start to end (max 93 days).

GET /api/v1/calendar/best-days

Returns ranked days with the highest scores for a specific purpose within a range (max 365 days).

GET /health

Unauthenticated health check for monitoring.

Response Example

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日（水）大安・一粒万倍日。結婚式・開業に大吉の日。"
}

Full response examples, field definitions, and error examples can be found in the examples section of the OpenAPI 3.1 Spec.

Use Cases

1. Wedding Venue AI Chatbot

"Recommend 5 good days for a wedding next month on weekends" → best-days?purpose=wedding&limit=5&exclude_weekdays=Mon,Tue,Wed,Thu,Fri

2. Moving Company AI Estimator

Return scores for a customer's preferred date and suggest alternatives → calendar/{date} for current score + range to find nearby high-score dates.

3. Fortune-telling SaaS

Automatically explain kanshi, rokuyo, and rekichu from birth dates or marriage registration dates → Sequential calls to calendar/{date}.

4. Calendar App Overlay

Bulk render rokuyo and rekichu in a monthly view → range?start=...&end=...

5. Business Automation (RPA / Agents)

Automatically set invoice issue dates to Daian, recommend auspicious days for contract signing, etc.

Pricing Plans

All plans include a Free tier of 10,000 requests/month. Usage beyond this is billed via transform_quantity[divide_by]=1000.

Contracts, billing, suspension, and resumption are fully automated via Stripe Webhooks (no human intervention required).

Authentication and Rate Limiting

API Key

Include shrb_ + 32 alphanumeric characters in the X-API-Key header:

X-API-Key: shrb_a1b2c3d4e5f67890...

Without a key, it operates under the anonymous Free tier (10,000 requests/month per IP).

Rate Limit Headers

All responses include:

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

Error Handling

All errors are returned in the standard format: { 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."
  }
}

See the ErrorCode section of the OpenAPI spec for details.

Precision and Methodology

• Lunar/Saku Calculation: Custom implementation based on astronomical algorithms (moon phase/solar longitude). Does not use simple 60-day cycle tables.

• Rokuyo: Deterministically derived from the lunar date (e.g., Lunar 1/1 → Sensho, 2/1 → Tomobiki).

• Rekichu: Covers 13 types including Ichiryumanbai-bi, Tensha-bi, Daimyo-nichi, Tora-no-hi, Mi-no-hi, Kishi-no-hi, Koushi-no-hi, Bosou-bi, Ten-on-bi, Fujoju-bi, Sanrinbo, Jushi-bi, and Jusshi-bi.

• 24 Solar Terms: Calculated at 15-degree solar longitude intervals, includes isToday flag.

• Kanshi: Full 60-cycle, including stems, branches, and animal labels.

• Range: 1873-01-01 to 2100-12-31 (post-Meiji 6 calendar reform).

Algorithms and methodology details are published as part of the OpenAPI spec and verified by 326 unit tests (see test/core/).

Tech Stack

• Runtime: Cloudflare Workers (Edge distributed)

• Framework: Hono

• Language: TypeScript (strict mode)

• MCP SDK: @modelcontextprotocol/sdk

• Billing: Stripe Billing (metered + transform_quantity)

• KV: Cloudflare KV (API keys, rate limiting, cache)

• Analytics: Cloudflare Analytics Engine (AI/Human UA classification, AI search referrer classification)

• Testing: Vitest (326 tests, all passing)

• CI/CD: GitHub Actions

• Monitoring: BetterStack

Local Development

# 依存関係
pnpm install

# 開発サーバー
pnpm run dev

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

# 型チェック
pnpm run typecheck

# npm パッケージ用 CLI ビルド
pnpm run build:cli

Deployment is via GitHub Actions only (wrangler deploy direct execution is prohibited).

Design Philosophy (AI-Native API)

Shirabe Calendar API is designed with the premise that "Generative AI will use it autonomously."

1. AI as Primary User: Designed for tasks chaining 10–50 requests.

2. Structured Data First: Immediate support for OpenAPI 3.1, MCP, and Function Calling.

3. No Human-Centric SaaS Bloat: No sign-up screens, no dashboards, no settings UI. Everything is handled via API and environment variables.

4. Auto-scaling: Contracts, billing, suspension, and resumption are fully automated via Stripe Webhooks.

This is an AI-native API: designed to be discovered and consumed by LLMs and autonomous agents, not by humans through a dashboard UI.

License

• API Service: Proprietary (Commercial use subject to paid plans)

• Sample Code/Client Examples in this repo: MIT

• Terms of Service: https://shirabe.dev/terms

• Contact: support@shirabe.dev

Related Links

• Production API: https://shirabe.dev

• OpenAPI 3.1 Spec: https://shirabe.dev/openapi.yaml

• MCP Endpoint: https://shirabe.dev/mcp

• Health Check: https://shirabe.dev/health

• Operator: Techwell Inc. (Fukuoka, Japan)

{
  "@context": "https://schema.org",
  "@type": "APIReference",
  "name": "Shirabe Calendar API",
  "description": "AI-native REST API and MCP server 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",
    "MCP server", "OpenAPI 3.1", "AI-native API",
    "ChatGPT GPTs", "Claude Tool Use", "Function Calling"
  ]
}