Shirabe Calendar API

Una API REST nativa para IA + servidor MCP que devuelve el calendario japonés (rokuyo, rekichu, eto, 24 términos solares) y juicios de auspiciosidad según el propósito con precisión astronómica. 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.

URL de producción: https://shirabe.dev ・ Especificación OpenAPI 3.1: https://shirabe.dev/openapi.yaml ・ MCP: https://shirabe.dev/mcp ・ Sitio oficial: https://shirabe.dev

Índice / Table of Contents

• ¿Qué es esto? / What is this?

• ¿Por qué Shirabe? / Why Shirabe

• Inicio rápido (REST)

• Integración con agentes de IA (MCP / GPTs / Function Calling)

• Lista de endpoints

• Ejemplos de respuesta

• Casos de uso

• Planes de precios

• Autenticación y límites de tasa

• Manejo de errores

• Precisión y base de cálculo

• Stack tecnológico

• Desarrollo local

• Licencia

Related MCP server: Edition Intelligence Platform

¿Qué es esto? / What is this?

Shirabe Calendar API es una API nativa para IA que proporciona información del calendario japonés con precisión astronómica. Devuelve en una sola solicitud: rokuyo, rekichu, eto, 24 términos solares, fecha del calendario lunar, era japonesa, además de juicios de auspiciosidad y puntuación según el propósito en 8 categorías (bodas, funerales, mudanzas, construcción, apertura de negocios, entrega de vehículos, registro de matrimonio y viajes). Cumple con OpenAPI 3.1. Se puede utilizar inmediatamente desde los principales frameworks de IA como ChatGPT GPTs Actions / Claude Tool Use / Gemini Function Calling / LangChain / LlamaIndex / Dify, entre otros.

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). Strict OpenAPI 3.1. Works out-of-the-box with ChatGPT GPTs Actions, Claude Tool Use, Gemini Function Calling, LangChain, LlamaIndex, and Dify.

Palabras clave / Keywords

API rokuyo API rekichu API taian API ichiryumanbaibi API tenshachi API calendario lunar API era japonesa API eto API 24 términos solares API calendario japonés API fecha de boda API fecha de mudanza AI calendar LLM calendar rokuyo api japanese calendar api lucky days api auspicious days japan mcp server japan openapi japanese calendar

¿Por qué Shirabe? / Why Shirabe

La implementación propia (código de cálculo de rokuyo mediante LLM) suele generar errores de cálculo. El cálculo del saku (luna nueva) del calendario lunar requiere precisión astronómica, algo que los algoritmos simples no pueden manejar. Shirabe incorpora un motor lunar astronómicamente preciso y cubre combinaciones complejas de rekichu (como Ichiryumanbaibi × Tenshachi).

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.

Inicio rápido (REST)

1. Pruébelo primero (sin autenticación, nivel gratuito hasta 10,000 al mes)

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

2. Llamada con clave 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. Generación automática desde la especificación 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

Integración con agentes de IA (MCP / GPTs / Function Calling)

Model Context Protocol (MCP)

Simplemente añada lo siguiente a claude_desktop_config.json para usarlo directamente desde Claude Desktop.

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

Los clientes compatibles con HTTP Streamable también pueden especificar la URL directamente:

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

Herramientas MCP públicas

ChatGPT GPTs Actions / Custom GPTs

En "Create new action" del GPT Builder, pegue lo siguiente en la URL de importación:

https://shirabe.dev/openapi.yaml

En Authentication, seleccione API Key (Header X-API-Key). Con esto, su GPT personalizado podrá llamar a Shirabe automáticamente.

Claude Tool Use / Anthropic SDK

Funciona con el patrón estándar de convertir OpenAPI a herramientas del SDK de anthropic. Consulte docs/claude-tool-use.md (en preparación) para más detalles.

Gemini Function Calling / LangChain / LlamaIndex / Dify

Está diseñado para que el operationId y los parámetros de OpenAPI 3.1 se conviertan directamente en firmas de funciones. Utilice el cargador OpenAPI de cada framework directamente.

Lista de endpoints

La especificación completa de todos los endpoints está definida en OpenAPI 3.1 (descripción, x-llm-hint, ejemplo y recoveryHint incluidos en japonés e inglés).

GET /api/v1/calendar/{date}

Devuelve la información del calendario y los juicios de auspiciosidad en 8 categorías para un día específico.

GET /api/v1/calendar/range

Devuelve la información del calendario para un periodo de start a end en un array (máximo 93 días).

GET /api/v1/calendar/best-days

Devuelve un ranking de los días con mayor puntuación para un propósito dentro de un periodo (máximo 365 días).

GET /health

Verificación de estado sin autenticación. Para sistemas de monitoreo.

Ejemplos de respuesta

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

Los ejemplos completos de respuesta, ejemplos de cada campo y ejemplos de error se pueden consultar en la sección examples de la especificación OpenAPI 3.1.

Casos de uso

1. Chatbot de IA para salones de bodas

"5 días recomendados para bodas el próximo mes" → best-days?purpose=wedding&limit=5&exclude_weekdays=lunes,martes,miércoles,jueves,viernes

2. IA de presupuestos para empresas de mudanzas

Devuelve la puntuación de la fecha deseada por el cliente y sugiere fechas alternativas → calendar/{date} para la puntuación del día + range para extraer días cercanos con alta puntuación.

3. SaaS de adivinación

Explicación automática de eto, rokuyo y rekichu a partir de la fecha de nacimiento o registro de matrimonio → llamadas consecutivas a calendar/{date}.

4. Superposición en aplicaciones de calendario

Dibujo masivo de rokuyo y rekichu en vistas mensuales → range?start=...&end=...

5. Automatización de procesos (RPA / Agentes)

Configurar automáticamente la fecha de emisión de facturas en días Taian, recomendar días auspiciosos para la firma de contratos, etc.

Planes de precios

Todos los planes incluyen 10,000 solicitudes gratuitas al mes. Se cobra por el exceso. Método transform_quantity[divide_by]=1000.

La contratación, facturación, suspensión y reactivación se procesan automáticamente mediante Stripe Webhook (sin intervención humana).

Autenticación y límites de tasa

Clave API

Incluya la clave alfanumérica de 32 caracteres precedida por shrb_ en el encabezado X-API-Key:

X-API-Key: shrb_a1b2c3d4e5f67890...

Si no se proporciona clave, funcionará bajo el nivel gratuito anónimo (10,000 por mes por IP).

Encabezados de límite de tasa

Todas las respuestas incluyen:

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

Manejo de errores

Todos los errores se devuelven en el formato común { 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."
  }
}

Consulte la sección ErrorCode de la especificación OpenAPI para más detalles.

Precisión y base de cálculo

• Cálculo lunar/saku: Implementación propia basada en algoritmos astronómicos (edad lunar, longitud eclíptica solar). No se utilizan tablas simples de ciclos de 60 días.

• Rokuyo: Derivado de forma determinista a partir de la fecha lunar (regla: 1/1 lunar → Sensho, 2/1 → Tomobiki, etc.).

• Rekichu: Cubre 13 tipos: Ichiryumanbaibi, Tenshachi, Daimyo-nichi, Tora-no-hi, Mi-no-hi, Kishi-no-hi, Kinoe-ne-no-hi, Bosho-nichi, Ten-on-nichi, Fujoju-nichi, Sanrinbo, Jushi-nichi, Jusshi-nichi.

• 24 términos solares: Calculados a intervalos de 15 grados de longitud eclíptica solar, con indicador de día actual (isToday).

• Eto: Ciclo completo de 60, etiquetas de tronco celestial, rama terrestre y animal.

• Rango soportado: 1873-01-01 a 2100-12-31 (desde la reforma del calendario Meiji 6).

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

Stack tecnológico

• Runtime: Cloudflare Workers (distribución en el borde)

• Framework: Hono

• Lenguaje: TypeScript (strict mode)

• MCP SDK: @modelcontextprotocol/sdk

• Facturación: Stripe Billing (pago por uso, medidor + transform_quantity)

• KV: Cloudflare KV (clave API, límite de tasa, caché)

• Medición: Cloudflare Analytics Engine (clasificación AI/humano UA, clasificación de referrers de búsqueda de IA)

• Pruebas: Vitest (326 pruebas, todas superadas)

• CI/CD: GitHub Actions

• Monitoreo: BetterStack

Desarrollo local

# 依存関係
pnpm install

# 開発サーバー
pnpm run dev

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

# 型チェック
pnpm run typecheck

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

El despliegue se realiza únicamente a través de GitHub Actions (prohibido ejecutar wrangler deploy directamente).

Filosofía de diseño del proyecto (API nativa para IA)

Shirabe Calendar API está diseñada bajo el criterio de que "la IA generativa la utilice por su cuenta".

1. La IA es el usuario principal: Diseño basado en la premisa de encadenar 10-50 solicitudes por tarea.

2. Prioridad a datos estructurados: Soporte inmediato para OpenAPI 3.1, MCP y Function Calling.

3. Eliminación de conceptos SaaS para humanos: Sin pantalla de registro, sin panel de control, sin pantalla de configuración. Todo se completa mediante API y variables de entorno.

4. Escalado automático: Automatización total de contratación, facturación, suspensión y reactivación mediante Stripe Webhook.

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

Licencia

• API service: Proprietary (el uso comercial sigue los planes de pago)

• Código de muestra y ejemplos de cliente en este repositorio: MIT

• Términos de servicio: https://shirabe.dev/terms

• Contacto: support@shirabe.dev

Enlaces relacionados

• API de producción: https://shirabe.dev

• Especificación OpenAPI 3.1: https://shirabe.dev/openapi.yaml

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

• Verificación de estado: https://shirabe.dev/health

• Operado por: Techwell Inc. (Fukuoka, Japón)

{
  "@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"
  ]
}