暦 API ドキュメント
エンドポイント仕様・レスポンス・エラー・レート制限
ベース URL: https://shirabe.dev。キーなしで月 10,000 回まで利用できます。
製品概要と料金はこちら。
クイックスタート
curl https://shirabe.dev/api/v1/calendar/2026-07-02有料プランのキーは X-API-Key ヘッダーで渡します(キーなし = 匿名 Free 扱い)。
エンドポイント一覧
| メソッド | パス | 説明 |
|---|---|---|
GET | /api/v1/calendar/{date} | 指定日の暦情報(六曜・暦注・干支・二十四節気・旧暦・和暦) |
GET | /api/v1/calendar/range | 期間の暦情報(六曜・暦注でフィルタ可) |
GET | /api/v1/calendar/best-days | 用途別の吉日ランキング(25+ 用途) |
GET | /health | ヘルスチェック(認証不要・カウント対象外) |
対応範囲: 1873-01-01 〜 2100-12-31。
GET /api/v1/calendar/{date}
例: GET /api/v1/calendar/2026-07-02(日付は YYYY-MM-DD)
レスポンス(実例、抜粋):
{
"date": "2026-07-02",
"wareki": "令和8年7月2日",
"day_of_week": { "ja": "木曜日", "en": "Thursday" },
"kyureki": { "year": 2026, "month": 5, "day": 18, "is_leap_month": false, "month_name": "皐月" },
"rokuyo": {
"name": "仏滅",
"reading": "ぶつめつ",
"description": "終日凶。万事に注意が必要",
"time_slots": { "morning": "凶", "noon": "凶", "afternoon": "凶", "evening": "凶" }
},
"kanshi": { "full": "丁丑", "jikkan": "丁", "junishi": "丑", "junishi_animal": { "ja": "牛", "en": "Ox" } },
"nijushi_sekki": { "name": "夏至", "reading": "げし" },
"rekichu": [ ... ],
"attribution": { ... }
}| フィールド | 意味 |
|---|---|
rokuyo | 六曜。名称・読み・説明と、時間帯別(time_slots)の吉凶 |
rekichu | 暦注(一粒万倍日・天赦日・三隣亡など)の配列 |
kanshi | 干支(十干十二支)。junishi_animal に日英の動物名 |
nijushi_sekki | 二十四節気(当日が節気の場合) |
kyureki / wareki | 旧暦(閏月フラグ付き)・和暦表記 |
GET /api/v1/calendar/range
例: 2026 年 7 月の大安・友引だけを取得:
curl "https://shirabe.dev/api/v1/calendar/range?start=2026-07-01&end=2026-07-31&filter_rokuyo=大安,友引"| パラメータ | 説明 |
|---|---|
start / end(必須) | 期間(YYYY-MM-DD) |
filter_rokuyo | 六曜名のカンマ区切り(例: 大安,友引) |
filter_rekichu | 暦注名のカンマ区切り(例: 天赦日) |
レスポンスは days 配列(各要素は単日取得と同じ形)。
GET /api/v1/calendar/best-days
例: 7〜8 月の結婚式向け吉日 上位 2 件:
curl "https://shirabe.dev/api/v1/calendar/best-days?purpose=wedding&start=2026-07-01&end=2026-08-31&limit=2"レスポンス(実例、抜粋):
{
"purpose": "wedding",
"period": { "start": "2026-07-01", "end": "2026-08-31" },
"best_days": [
{
"rank": 1,
"date": "2026-07-03",
"rokuyo": "大安",
"rekichu": ["母倉日", "天恩日", "寅の日"],
"judgment": "大吉",
"score": 10,
"note": "大安は終日吉で結婚式に最適な日です。…",
"day_of_week": "金曜日"
}
]
}| パラメータ | 説明 |
|---|---|
purpose(必須) | 用途 slug。wedding / moving / jichinsai / company-incorporation / contract-signing など 25 以上(全一覧は OpenAPI 定義を参照) |
start / end(必須) | 検索期間 |
limit | 返す件数 |
min_score / exclude_weekdays | スコア下限・曜日除外 |
note に判定根拠(六曜 + 暦注の組み合わせ)が日本語で入るため、
エージェントの回答にそのまま引用できます。
エラー
エラーは全て次の形で返ります:
{ "error": { "code": "...", "message": "..." } }| HTTP | code(代表) | 意味と対処 |
|---|---|---|
| 400 | INVALID_DATE / INVALID_PARAMETER | 日付形式・範囲・パラメータ不正。カウントされません |
| 401 | INVALID_API_KEY | 形式不正・未登録のキー。キーを外すと匿名 Free で通ります |
| 429 | RATE_LIMIT_EXCEEDED / USAGE_LIMIT_EXCEEDED | 秒間または月間上限。Retry-After と次プランへの next_plan.checkout_path(→ /calendar/buy)を同梱 |
レート制限とカウント規則
| プラン | 月間上限 | 秒間レート |
|---|---|---|
| Free | 10,000 回 | 1 req/s |
| Starter | 500,000 回 | 30 req/s |
| Pro | 5,000,000 回 | 100 req/s |
| Enterprise | 無制限 | 500 req/s |
- 1 リクエスト = 1 カウント(
/rangeも日数によらず 1 リクエスト 1 カウント) - 400 系・401 はカウントされません(無料枠を消費しない)
- 残量はレスポンスヘッダー
X-RateLimit-Limit/X-RateLimit-Remainingで確認できます - 月間カウントは毎月 1 日 0:00 UTC にリセット
AI 統合・機械可読仕様
- OpenAPI 3.1(完全版):
https://shirabe.dev/openapi.yaml - OpenAPI(GPTs Actions 用短縮版):
https://shirabe.dev/openapi-gpts.yaml - リモート MCP サーバー:
https://shirabe.dev/mcp(暦・住所・テキスト・法人番号の tool)