Koyomi API 使用説明書

エンドポイント、パラメータ、レスポンス例、活用方法をまとめたガイドです。

トップへ戻る APIフォーム お問い合わせ

目次

  1. 概要
  2. エンドポイント
  3. パラメータ
  4. 使用例
  5. レスポンス
  6. 項目別の意味
  7. エラー例
  8. 活用方法
  9. Message API（文章生成向け）

概要

このAPIは、生年月日などを入力すると暦に関する詳細な情報を返します。Node.js + Express.js で構築され、Docker で運用されます。

エンドポイント

/api/koyomi

パラメータ

パラメータ型説明必須
birthdaystring生年月日（YYYYMMDD）○
datestring対象日（YYYYMMDD）※単一日×
fromstring範囲開始日（YYYYMMDD）×
tostring範囲終了日（YYYYMMDD）×
genderstringm または f。文面生成や相性等、性別を参照する機能向け。省略可。×

※ date もしくは from & to のどちらかを指定してください（範囲は最大31日）。

使用例

単一日

curl "https://your-domain.example.com/api/koyomi?birthday=19730805&date=20250701"

範囲指定（最大31日まで）

curl "https://your-domain.example.com/api/koyomi?birthday=19730805&from=20250701&to=20250705"

レスポンス

{
  "status": 200,
  "message": "success",
  "profile": {
    "year": 1973,
    "month": 8,
    "day": 5,
    "kazoe": 53,
    "day10kan": "癸",
    "day12shi": "酉",
    "daynatchin": "剣鋒金",
    "daygogyou": "金行",
    "year10kan": "癸",
    "year12shi": "丑",
    "sei10kan": "水",
    "sei12shi": "土",
    "yearnatchin": "桑柘木",
    "yeargogyou": "木行",
    "kuyou": "計都星",
    "shugo": {
      "hakke": "【☶】艮上連（ごんじょうれん）",
      "honzon": ["虚空蔵菩薩", "釈迦如来", "普賢菩薩", "文殊菩薩"]
    }
  },
  "calendar": [ ... 日別データ ... ]
}

profile／calendar の主な項目

profile

項目意味・説明
kazoe数え年（生まれた年を1歳と数える東洋の年齢）
day10kan / day12shi誕生日の十干・十二支
daynatchin / daygogyou日の納音／五行
year10kan / year12shi生年の十干／十二支
yearnatchin / yeargogyou年の納音／五行
kuyou九曜星
shugo八卦・守本尊など

calendar

項目意味・説明
SetYEAR / SetMON / SetDAY対象日の年月日
youbi曜日
jikkan / junishi対象日の十干／十二支
sekki二十四節気
gyoji節句・祝祭日・年中行事
choku二十八直
syuku27 / syuku28二十七宿／二十八宿
gedan暦注下段
senjitsu選日
qreki旧暦（[年, 月, 日, 閏月情報]）

エラー例

誕生日が未指定：

{
  "status": 400,
  "message": "birthday is required (YYYYMMDD)"
}

範囲が31日を超過：

{
  "status": 400,
  "message": "range must be ≤ 31 days (requested 35 days)"
}

活用方法

📧 メールテンプレートとして使用

件名：暦情報のご案内（1973年8月5日生まれ）
本文：
・年の納音：桑柘木
・守本尊：虚空蔵菩薩 ほか
【2025-07-01】
・干支：辛未
・選日：大犯土
...

📄 PDF化の例

pandoc response.md -o response.pdf

Message API（文章生成向け）

エンドポイント

GET https://api.kitagawakazutaka.com/message/:date

パスパラメータ

名前型説明必須
:datestring対象日（例：2025-07-12）✔

クエリパラメータ

名前型説明必須
birthdaystring生年月日（YYYYMMDD）✔
formatstringmail または web（改行形式）✘（既定：mail）
genderstringm / f。文面の表現や相性などに利用。✘
apikeystring認証用APIキー（将来必須化予定）✘

レスポンス例

{
  "date": "2025-07-12",
  "title": "今日は壬午の日",
  "body": "📅 2025年7月12日（土）\n\n🌟 本日の干支は「壬午」です。\n🔯 二十四節気：..."
}

エラー例

{
  "status": 400,
  "message": "birthday is required (YYYYMMDD)"
}