{
  "openapi": "3.1.0",
  "info": {
    "title": "シルギア 暦API",
    "version": "1.0.0",
    "description": "登録不要・無料の暦API。1900〜2100年の毎日について、旧暦・六曜・干支・二十四節気・雑節・月齢・和暦を返します。天文計算は NASA JPL の天体暦 DE440s（skyfield）。説明: https://api.shirugear.com/koyomi/ 。v1 の中では項目を足すことはあっても、名前や意味は変えません（知らない項目は無視してください）。六曜・干支などの暦注は迷信・慣習としての参考情報で、科学的な根拠を示すものではありません。",
    "termsOfService": "https://api.shirugear.com/terms/",
    "contact": {
      "name": "アナライズギア株式会社（シルギア）",
      "url": "https://shirugear.com/contact"
    }
  },
  "servers": [
    {
      "url": "https://api.shirugear.com"
    }
  ],
  "paths": {
    "/koyomi/v1/{year}.json": {
      "get": {
        "summary": "その年の暦（1日ずつ）と、二十四節気・雑節・月の満ち欠けの一覧",
        "operationId": "getKoyomiYear",
        "parameters": [
          {
            "name": "year",
            "in": "path",
            "required": true,
            "description": "西暦の年（半角数字4桁。1900〜2100）",
            "schema": {
              "type": "string",
              "pattern": "^[0-9]{4}$",
              "examples": [
                "2026"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "その年の暦",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KoyomiYearResponse"
                }
              }
            }
          },
          "400": {
            "description": "年の形が正しくない（invalid_year）",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "1900〜2100年の外（year_not_found）",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "GET / HEAD 以外（method_not_allowed）",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/koyomi/v1/meta.json": {
      "get": {
        "summary": "データの版・期間・計算のもと・日数",
        "operationId": "getKoyomiMeta",
        "responses": {
          "200": {
            "description": "データの版など",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KoyomiMetaResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "LunarDate": {
        "type": "object",
        "description": "旧暦の日付（天保暦の決め方。新月の日を1日とし、冬至を含む月を11月とする。2033-12-22 からは閏11月）",
        "required": [
          "year",
          "month",
          "day",
          "leap",
          "text"
        ],
        "properties": {
          "year": {
            "type": "integer",
            "description": "旧暦の年。旧暦の1月1日がある西暦の年（旧正月より前の日は前の年）"
          },
          "month": {
            "type": "integer",
            "minimum": 1,
            "maximum": 12,
            "description": "旧暦の月。閏月も同じ番号"
          },
          "day": {
            "type": "integer",
            "minimum": 1,
            "maximum": 30
          },
          "leap": {
            "type": "boolean",
            "description": "閏月なら true"
          },
          "text": {
            "type": "string",
            "description": "表示用",
            "examples": [
              "1月1日",
              "閏11月1日"
            ]
          }
        }
      },
      "KoyomiDay": {
        "type": "object",
        "description": "1日分の暦",
        "required": [
          "date",
          "weekday",
          "wareki",
          "lunar",
          "rokuyo",
          "kanshi",
          "kanshi_kana",
          "sekki",
          "zassetsu",
          "moon_age",
          "moon_phase"
        ],
        "properties": {
          "date": {
            "type": "string",
            "format": "date",
            "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"
          },
          "weekday": {
            "type": "string",
            "enum": [
              "日",
              "月",
              "火",
              "水",
              "木",
              "金",
              "土"
            ]
          },
          "wareki": {
            "type": "string",
            "description": "その日の和暦の年。未来の日付も今の元号のまま",
            "examples": [
              "令和8年",
              "平成元年"
            ]
          },
          "lunar": {
            "$ref": "#/components/schemas/LunarDate"
          },
          "rokuyo": {
            "type": "string",
            "description": "六曜。（旧暦の月＋旧暦の日）を6で割った余り: 0 大安・1 赤口・2 先勝・3 友引・4 先負・5 仏滅",
            "enum": [
              "先勝",
              "友引",
              "先負",
              "仏滅",
              "大安",
              "赤口"
            ]
          },
          "kanshi": {
            "type": "string",
            "description": "日の干支（60日周期。1900-01-01 が 甲戌）",
            "examples": [
              "壬戌"
            ]
          },
          "kanshi_kana": {
            "type": "string",
            "description": "日の干支の読み（ひらがな）",
            "examples": [
              "みずのえいぬ"
            ]
          },
          "sekki": {
            "type": [
              "string",
              "null"
            ],
            "description": "その日に入る二十四節気。無ければ null",
            "enum": [
              "小寒",
              "大寒",
              "立春",
              "雨水",
              "啓蟄",
              "春分",
              "清明",
              "穀雨",
              "立夏",
              "小満",
              "芒種",
              "夏至",
              "小暑",
              "大暑",
              "立秋",
              "処暑",
              "白露",
              "秋分",
              "寒露",
              "霜降",
              "立冬",
              "小雪",
              "大雪",
              "冬至",
              null
            ]
          },
          "zassetsu": {
            "type": "array",
            "description": "その日の雑節の表示用の名前（年の zassetsu の label）。無ければ空",
            "items": {
              "type": "string"
            },
            "examples": [
              [
                "夏の土用の丑の日"
              ]
            ]
          },
          "moon_age": {
            "type": "number",
            "minimum": 0,
            "maximum": 30,
            "description": "月齢。その日の正午（日本時間）の、直前の新月からの経過日数（小数1桁）"
          },
          "moon_phase": {
            "type": [
              "string",
              "null"
            ],
            "description": "その日に新月・上弦・満月・下弦の瞬間があればその名前。無ければ null",
            "enum": [
              "新月",
              "上弦",
              "満月",
              "下弦",
              null
            ]
          }
        }
      },
      "SolarTerm": {
        "type": "object",
        "required": [
          "name",
          "kana",
          "longitude",
          "date",
          "at"
        ],
        "properties": {
          "name": {
            "type": "string",
            "enum": [
              "小寒",
              "大寒",
              "立春",
              "雨水",
              "啓蟄",
              "春分",
              "清明",
              "穀雨",
              "立夏",
              "小満",
              "芒種",
              "夏至",
              "小暑",
              "大暑",
              "立秋",
              "処暑",
              "白露",
              "秋分",
              "寒露",
              "霜降",
              "立冬",
              "小雪",
              "大雪",
              "冬至"
            ]
          },
          "kana": {
            "type": "string",
            "description": "読み（ひらがな）"
          },
          "longitude": {
            "type": "integer",
            "minimum": 0,
            "maximum": 345,
            "multipleOf": 15,
            "description": "太陽の地心視黄経（度）。30の倍数が中気"
          },
          "date": {
            "type": "string",
            "format": "date",
            "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"
          },
          "at": {
            "type": "string",
            "format": "date-time",
            "description": "日本時間（+09:00）・秒まで",
            "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\\+09:00$",
            "examples": [
              "2026-02-04T05:02:08+09:00"
            ]
          }
        }
      },
      "Zassetsu": {
        "type": "object",
        "required": [
          "name",
          "label",
          "date"
        ],
        "properties": {
          "name": {
            "type": "string",
            "enum": [
              "節分",
              "彼岸入り",
              "彼岸明け",
              "八十八夜",
              "入梅",
              "半夏生",
              "二百十日",
              "二百二十日",
              "土用入り",
              "土用の丑の日"
            ]
          },
          "season": {
            "type": "string",
            "enum": [
              "春",
              "夏",
              "秋",
              "冬"
            ],
            "description": "彼岸・土用だけ。ほかは項目ごと無い"
          },
          "label": {
            "type": "string",
            "description": "表示用の名前",
            "examples": [
              "夏の土用入り",
              "彼岸入り（春）",
              "節分"
            ]
          },
          "date": {
            "type": "string",
            "format": "date",
            "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"
          },
          "at": {
            "type": "string",
            "format": "date-time",
            "description": "入梅・半夏生・土用入り（太陽の黄経で決まるもの）だけ。ほかは項目ごと無い。日本時間・秒まで",
            "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\\+09:00$",
            "examples": [
              "2026-02-04T05:02:08+09:00"
            ]
          }
        }
      },
      "MoonPhase": {
        "type": "object",
        "required": [
          "name",
          "date",
          "at"
        ],
        "properties": {
          "name": {
            "type": "string",
            "enum": [
              "新月",
              "上弦",
              "満月",
              "下弦"
            ]
          },
          "date": {
            "type": "string",
            "format": "date",
            "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"
          },
          "at": {
            "type": "string",
            "format": "date-time",
            "description": "日本時間（+09:00）・秒まで",
            "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\\+09:00$",
            "examples": [
              "2026-02-04T05:02:08+09:00"
            ]
          }
        }
      },
      "KoyomiYearResponse": {
        "type": "object",
        "required": [
          "year",
          "wareki",
          "kanshi",
          "kanshi_kana",
          "days",
          "solar_terms",
          "zassetsu",
          "moon_phases",
          "data_version"
        ],
        "properties": {
          "year": {
            "type": "integer",
            "minimum": 1900,
            "maximum": 2100
          },
          "wareki": {
            "type": "string",
            "description": "和暦の年。年の途中で元号が変わる年は「・」でつなぐ",
            "examples": [
              "令和8年",
              "昭和64年・平成元年"
            ]
          },
          "kanshi": {
            "type": "string",
            "description": "年の干支（西暦の年で決め、1月1日で切り替える）",
            "examples": [
              "丙午"
            ]
          },
          "kanshi_kana": {
            "type": "string",
            "examples": [
              "ひのえうま"
            ]
          },
          "days": {
            "type": "array",
            "description": "1月1日〜12月31日の毎日（365件。うるう年は366件）",
            "minItems": 365,
            "maxItems": 366,
            "items": {
              "$ref": "#/components/schemas/KoyomiDay"
            }
          },
          "solar_terms": {
            "type": "array",
            "description": "その年の二十四節気（日付の順）",
            "items": {
              "$ref": "#/components/schemas/SolarTerm"
            }
          },
          "zassetsu": {
            "type": "array",
            "description": "その年の雑節（日付の順）",
            "items": {
              "$ref": "#/components/schemas/Zassetsu"
            }
          },
          "moon_phases": {
            "type": "array",
            "description": "その年の新月・上弦・満月・下弦（日付の順）",
            "items": {
              "$ref": "#/components/schemas/MoonPhase"
            }
          },
          "data_version": {
            "type": "string",
            "description": "データの版（元データが変わった日。祝日・営業日APIと共通）",
            "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
            "examples": [
              "2026-11-01"
            ]
          }
        }
      },
      "KoyomiMetaResponse": {
        "type": "object",
        "required": [
          "data_version",
          "built_at",
          "from",
          "to",
          "sources",
          "counts"
        ],
        "properties": {
          "data_version": {
            "type": "string",
            "description": "データの版（元データが変わった日。祝日・営業日APIと共通）",
            "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
            "examples": [
              "2026-11-01"
            ]
          },
          "built_at": {
            "type": "string",
            "format": "date-time",
            "description": "データを作った日時（ISO 8601・UTC）"
          },
          "from": {
            "type": "integer",
            "examples": [
              1900
            ]
          },
          "to": {
            "type": "integer",
            "examples": [
              2100
            ]
          },
          "sources": {
            "type": "object",
            "required": [
              "astronomy"
            ],
            "properties": {
              "astronomy": {
                "type": "string",
                "description": "天文計算のもと",
                "examples": [
                  "JPL DE440s / skyfield 1.55"
                ]
              }
            }
          },
          "counts": {
            "type": "object",
            "required": [
              "days"
            ],
            "properties": {
              "days": {
                "type": "integer",
                "description": "全期間の日数",
                "examples": [
                  73414
                ]
              }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "status",
              "code",
              "message"
            ],
            "properties": {
              "status": {
                "type": "integer",
                "enum": [
                  400,
                  404,
                  405
                ]
              },
              "code": {
                "type": "string",
                "description": "エラーの種類（固定の値）",
                "enum": [
                  "invalid_year",
                  "year_not_found",
                  "not_found",
                  "method_not_allowed"
                ]
              },
              "message": {
                "type": "string",
                "description": "説明文（言い回しは変わることがある）"
              }
            }
          }
        }
      }
    }
  }
}