REFERENCE

API仕様書

公開資料の本文です。サンプルとあわせてご確認ください。

ベストカレンダー 暦API 仕様書（v1）

提供状態: 提供開始前（予定仕様）。 提供開始日はご相談のうえ個別にご案内します。 この文書の内容は提供開始までに変わることがあります。変更は更新履歴でお知らせします。

1. 概要

六曜・旧暦、吉日・選日等 11 種、二十四節気・雑節、日干支、月齢・月相・朔弦望、国民の祝日・休日、 月食・スーパームーン（標準 7 資産）を、日単位・月単位の JSON で返します。

回数・速度は、提供前に負荷を確認して確定する設計値です。

2. 認証

Authorization: Bearer bck_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

- APIキーはサーバー側だけに置いてください。公開する JavaScript・アプリの配布物・リポジトリに含めないでください。

- キーの交換（新しいキーの発行と、旧キーの期限付き失効）と失効はご依頼に応じて行います。失効の反映には最大 30 秒かかります。

3. エンドポイント

ベース URL: https://bestcalendar.jp/koyomi-api/v1

応答（/days）

{
  "schema": "koyomi-offering-api/1",
  "kind": "day",
  "day_schema": "koyomi-offering-day/1",
  "data": {
    "date": "2027-01-22", "weekday": 4, "weekday_ja": "金",
    "kyureki": {"status": "ok", "year": 2026, "month": 12, "leap_month": false, "day": 15, "rokuyou": "友引"},
    "luckydays": {"status": "ok", "names": ["神吉日"]},
    "solar": {"status": "ok", "events": []},
    "kanshi": {"status": "ok", "jikkan": "辛", "junishi": "丑", "label": "辛丑"},
    "moon": {"status": "ok", "age": 14.3, "phase": "満月", "phase_time": "2027-01-22T21:17:23+09:00"},
    "holidays": {"status": "ok", "is_holiday": false, "name": null, "basis": "cao_published"},
    "moon_events": {"status": "ok", "eclipses": [], "supermoons": [{"date": "2027-01-22", "label_ja": "スーパームーン", "...": "..."}]}
  },
  "versions": {"snapshot_id": "…", "assets": {"kyureki": "…", "...": "…"}, "holidays_source": {"…": "…"}}
}

/months は data の代わりに year・month・days（その月の全日の配列）を返します。 各項目の型・単位・時刻基準・出典・定義は項目辞書（dictionary.md）にあります。納品パックの JSON の days と同じ形です。

欠損と「該当なし」

各資産の status が "ok" なら値があります。そのうえでの空配列・null は「その日に該当なし」です。 "unavailable" のときは値が無く、reason（unsupported_year / no_data）を持ちます。この 2 つを区別してください。

祝日の確定度

holidays.basis が cao_published なら内閣府が公表済みの年、estimated なら現行法の規定からの推定です （春分・秋分の日は前年 2 月の官報で確定します）。確定したら値と版を更新します。

4. 応答ヘッダー

5. エラー

本文は {"error": {"code": "...", "message": "..."}} です。

6. おすすめの使い方

お客様のサーバーで月単位に取得して保存し、画面は保存したデータを読む構成をおすすめします。 画面の表示回数と API の回数を結び付けないでください。

# 例: 毎日 1 回、今年と来年の各月を取り直して保存する（Python・サーバー側）
import json, os, time, urllib.request

KEY = os.environ["KOYOMI_API_KEY"]          # 環境変数などサーバーだけに置く
BASE = "https://bestcalendar.jp/koyomi-api/v1"

def fetch_month(ym, etag=None):
    req = urllib.request.Request(f"{BASE}/months/{ym}", headers={"Authorization": f"Bearer {KEY}"})
    if etag:
        req.add_header("If-None-Match", etag)
    try:
        with urllib.request.urlopen(req) as res:
            return json.load(res), res.headers["ETag"]
    except urllib.error.HTTPError as e:
        if e.code == 304:
            return None, etag                 # 変化なし（回数に数えない）
        raise

for year in (2026, 2027):
    for month in range(1, 13):
        ym = f"{year}-{month:02d}"
        # 保存済みの ETag を読み、変わっていれば上書きする（保存先はお客様の DB・ファイル）
        data, etag = fetch_month(ym, etag=None)
        time.sleep(1.1)                       # 毎秒 1 回

// 例: Node.js（サーバー側）。ブラウザの JavaScript にキーを書かないこと
const res = await fetch("https://bestcalendar.jp/koyomi-api/v1/days/2027-01-22", {
  headers: { Authorization: `Bearer ${process.env.KOYOMI_API_KEY}` },
});
if (res.status === 429) { /* Retry-After 秒待って再試行 */ }
const body = await res.json();

AI の開発ツールで実装するときも、この仕様書と項目辞書・サンプル JSON を材料にできます。 画面に出す日付や暦の値は、生成したコードや文章ではなく、API から取得したデータを使ってください。

7. 契約の終了

- 契約終了日の翌日から、キー・新しい取得・更新通知・問い合わせ窓口は使えなくなります。

- 契約中に取得して保存したデータは、同じサービスで引き続き利用できます（一律の削除義務はありません）。

- 暦データ自体を第三者へ販売・配布すること（データ商品・API としての再提供）はできません。

8. 含まないもの

専用 SLA・24 時間の有人対応、お客様の実装の代行、納品パックの確認表 PDF・年次 zip、 日の出入・月の出入と天体配置（個別見積）、九星・十二直・二十八宿など当社が保有しない暦注。