REFERENCE

API仕様書

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

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

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

1. 概要

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

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

速度はサーバーに届いた時刻で数えます。通信の遅れで到着が詰まることがあるので、連続して取るときは 2 秒あけるか、429 rate_limited が返ったら Retry-After（1 秒）だけ待って同じ要求をやり直してください。やり直した要求は、成功すれば 1 回として数えます（429 は数えません）。

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": "スーパームーン", "...": "..."}]},
    "entities": []
  },
  "versions": {"snapshot_id": "…", "assets": {"kyureki": "…", "...": "…"}, "holidays_source": {"…": "…"}}
}

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

暦の実体（entities）

資産は暦法の値で、実体はその上に載る名前です。たとえば solar には「土用」は出ますが、 「土用の丑の日」は出ません。それは「土用の範囲 × 日干支」を組んだ結果に付く名前で、日をいくつ取っても返らないからです。 entities はその名前を、その日について返します。

"entities": [{"slug": "soko", "name": "霜降", "reading": "そうこう", "kind": "sekki"}]

- 該当なしの日は空配列です（欠損ではありません。実体は毎日立つものではありません）

- kind は holiday（国民の祝日）/ sekki（二十四節気）/ zassetsu（雑節）/ gyoji（行事）/ sun（日の出入に関わるもの。初日の出）/ luckyday（暦注の日。吉日の一粒万倍日・天赦日・寅の日・巳の日・己巳の日・戌の日と、凶日の不成就日・三隣亡）です

- 同じ日に複数立つことがあります（例: 2026-10-23 は霜降・十三夜・一粒万倍日・三隣亡の 4 件）。1 件に潰していません

- slug で GET /entities/{slug} を引くと、その年に立つ日・成立の規則・出典・引ける年が取れます

- 1 年に複数回立つ実体があります（土用は年 4 回、お彼岸は年 2 回、土用の丑の日は二の丑がある年は 2 回。吉日はさらに多く、一粒万倍日は年 57〜64 回、寅の日・巳の日は 30〜31 回、天赦日は 5〜7 回）。/entities/{slug} の dates はその年の全件です。 お彼岸のように期間を持つ実体は、返すのは入りの日です（中日は入りの 3 日後、明けは 6 日後）

応答（/entities/{slug}）

{
  "schema": "koyomi-offering-api/1",
  "kind": "entity",
  "data": {
    "slug": "doyo", "name": "土用", "reading": "どよう",
    "aliases": ["土用入り", "春の土用", "夏の土用", "秋の土用", "冬の土用"],
    "kind": "zassetsu", "resolver": "solar",
    "definition": [{"year_from": 1926, "year_to": null,
                    "rule": "年4回。太陽黄経が 27／117／207／297 度に達した日が土用入りで、明けは次の立春・立夏・立秋・立冬の前日",
                    "source": "国立天文台 暦要項（雑節）"}],
    "ground_truth": {"basis": "astronomical", "authority": "国立天文台 暦計算室（暦要項）", "method": null},
    "years": {"from_year": 2025, "to_year": 2028},
    "year": 2027,
    "dates": ["2027-01-17", "2027-04-17", "2027-07-20", "2027-10-21"]
  },
  "versions": {"...": "..."}
}

years は契約で取得できる年の範囲で切ったものです（実体そのものが存在する年の範囲とは別です。 たとえばスポーツの日は 2020 年から存在しますが、years は契約の年窓を超えません）。 definition は成立の規則が変わった順に並びます（スポーツの日は 2020 年・2021 年の五輪特例を経て、 2022 年から 10 月の第 2 月曜日）。ground_truth は日付の正しさを何で担保しているかで、 一次資料が存在しない実体は authority にそう書いてあります。 出典の表示は `basis` からではなく `authority` の文字列から作ってください。 春分の日のように、法律が日付を定めず（祝日法は「春分日」とだけ定めます）、 日付そのものは国立天文台の計算が官報の暦要項で確定する実体があり、authority に 2 つの当局が入ります。

欠損と「該当なし」

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

祝日の確定度

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

4. 応答ヘッダー

5. エラー

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

今月の上限に達した後は、If-None-Match を付けた要求にも 429 を返します。 毎秒の上限は、エラーになった要求にも適用されます。

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(2)                         # 毎秒 1 回。到着が詰まらないよう 2 秒あける

// 例: 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、 日の出入・月の出入と天体配置（個別見積）、九星（年・月・日。年と月の九星は当社の暦データにあるが、API と納品パックには含まない）・十二直・二十八宿など、API で提供していない暦注。