{
  "openapi": "3.1.0",
  "info": {
    "title": "シルギア 和暦・元号API",
    "version": "1.0.0",
    "description": "登録不要・無料の和暦・元号API。明治・大正・昭和・平成・令和の始まりと終わりの日と根拠、1868〜2100年の西暦の各年に当たる和暦の年とその期間、元号ごとの各年が西暦のいつからいつまでかを返します。西暦 = 和暦の年 + offset（例: 令和8年 = 8 + 2018 = 2026年）。大正・昭和は改元の当日から、平成・令和は元号を改める政令の施行日から新しい元号です。明治5年（1872年）までは旧暦のため、和暦の年の区切りは旧暦の元日です（1869年は明治元年1月1日〜2月10日・明治2年2月11日〜）。令和は次の元号が決まっていないため、2100年まで今の元号のまま数えます。元号法・元号を改める政令・内閣府・国立公文書館・国立天文台の資料で確認して作成。説明: https://api.shirugear.com/wareki/ 。v1 の中では項目や元号を足すことはあっても、名前や意味は変えません（知らない項目は無視してください）。",
    "termsOfService": "https://api.shirugear.com/terms/",
    "contact": {
      "name": "アナライズギア株式会社（シルギア）",
      "url": "https://shirugear.com/contact"
    }
  },
  "servers": [
    {
      "url": "https://api.shirugear.com"
    }
  ],
  "paths": {
    "/wareki/v1/eras.json": {
      "get": {
        "summary": "元号の一覧（始まりと終わりの日・offset・根拠）",
        "operationId": "getEras",
        "responses": {
          "200": {
            "description": "5つの元号",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Eras"
                }
              }
            }
          },
          "403": {
            "description": "日本国内以外から",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "GET/HEAD以外",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/wareki/v1/{year}.json": {
      "get": {
        "summary": "西暦の年に当たる和暦と、それぞれの期間",
        "operationId": "getYear",
        "parameters": [
          {
            "name": "year",
            "in": "path",
            "required": true,
            "description": "西暦の年（4桁・1868〜2100）",
            "schema": {
              "type": "string",
              "pattern": "^[0-9]{4}$"
            },
            "example": "1989"
          }
        ],
        "responses": {
          "200": {
            "description": "その年の和暦",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Year"
                }
              }
            }
          },
          "400": {
            "description": "URLの形が違う（2桁の年・一覧に無い元号の名前など）",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "日本国内以外から",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "範囲外の年（1868〜2100年以外）",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "GET/HEAD以外",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/wareki/v1/meiji.json": {
      "get": {
        "summary": "明治の各年（西暦のいつからいつまでか）",
        "operationId": "getEraMeiji",
        "responses": {
          "200": {
            "description": "明治の各年",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EraYears"
                }
              }
            }
          },
          "403": {
            "description": "日本国内以外から",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "GET/HEAD以外",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/wareki/v1/taisho.json": {
      "get": {
        "summary": "大正の各年（西暦のいつからいつまでか）",
        "operationId": "getEraTaisho",
        "responses": {
          "200": {
            "description": "大正の各年",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EraYears"
                }
              }
            }
          },
          "403": {
            "description": "日本国内以外から",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "GET/HEAD以外",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/wareki/v1/showa.json": {
      "get": {
        "summary": "昭和の各年（西暦のいつからいつまでか）",
        "operationId": "getEraShowa",
        "responses": {
          "200": {
            "description": "昭和の各年",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EraYears"
                }
              }
            }
          },
          "403": {
            "description": "日本国内以外から",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "GET/HEAD以外",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/wareki/v1/heisei.json": {
      "get": {
        "summary": "平成の各年（西暦のいつからいつまでか）",
        "operationId": "getEraHeisei",
        "responses": {
          "200": {
            "description": "平成の各年",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EraYears"
                }
              }
            }
          },
          "403": {
            "description": "日本国内以外から",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "GET/HEAD以外",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/wareki/v1/reiwa.json": {
      "get": {
        "summary": "令和の各年（西暦のいつからいつまでか）",
        "operationId": "getEraReiwa",
        "responses": {
          "200": {
            "description": "令和の各年",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EraYears"
                }
              }
            }
          },
          "403": {
            "description": "日本国内以外から",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "GET/HEAD以外",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/wareki/v1/meta.json": {
      "get": {
        "summary": "データの版・範囲・出典",
        "operationId": "getMeta",
        "responses": {
          "200": {
            "description": "版",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Meta"
                }
              }
            }
          },
          "403": {
            "description": "日本国内以外から",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Source": {
        "type": "object",
        "required": [
          "label",
          "url"
        ],
        "properties": {
          "label": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "Era": {
        "type": "object",
        "required": [
          "key",
          "name",
          "kana",
          "romaji",
          "start",
          "end",
          "proclaimed",
          "last_year",
          "offset",
          "basis"
        ],
        "properties": {
          "key": {
            "type": "string",
            "enum": [
              "meiji",
              "taisho",
              "showa",
              "heisei",
              "reiwa"
            ]
          },
          "name": {
            "type": "string",
            "description": "元号（例: 令和）"
          },
          "kana": {
            "type": "string",
            "description": "読み（ひらがな）"
          },
          "romaji": {
            "type": "string"
          },
          "start": {
            "type": "string",
            "format": "date",
            "description": "最初の日（グレゴリオ暦）"
          },
          "end": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "最後の日。今の元号（令和）は null"
          },
          "proclaimed": {
            "type": "string",
            "format": "date",
            "description": "改元を定めた日（改元の詔・詔書の日、または元号を改める政令の公布日）"
          },
          "last_year": {
            "type": [
              "integer",
              "null"
            ],
            "description": "最後の年。令和は null"
          },
          "offset": {
            "type": "integer",
            "description": "西暦 = 和暦の年 + offset"
          },
          "basis": {
            "type": "object",
            "required": [
              "text",
              "sources"
            ],
            "properties": {
              "text": {
                "type": "string"
              },
              "sources": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Source"
                }
              }
            }
          }
        }
      },
      "Eras": {
        "type": "object",
        "required": [
          "eras",
          "note",
          "data_version"
        ],
        "properties": {
          "eras": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Era"
            }
          },
          "note": {
            "type": "string"
          },
          "data_version": {
            "type": "string",
            "format": "date"
          }
        }
      },
      "YearEra": {
        "type": "object",
        "required": [
          "era",
          "key",
          "year",
          "label",
          "from",
          "to"
        ],
        "properties": {
          "era": {
            "type": "string",
            "description": "元号（例: 平成）"
          },
          "key": {
            "type": "string",
            "enum": [
              "meiji",
              "taisho",
              "showa",
              "heisei",
              "reiwa"
            ]
          },
          "year": {
            "type": "integer",
            "minimum": 1,
            "description": "和暦の年（元年は 1）"
          },
          "label": {
            "type": "string",
            "description": "例: 平成元年"
          },
          "from": {
            "type": "string",
            "format": "date",
            "description": "その西暦の年の中での期間の最初の日"
          },
          "to": {
            "type": "string",
            "format": "date",
            "description": "その西暦の年の中での期間の最後の日"
          }
        }
      },
      "Year": {
        "type": "object",
        "required": [
          "year",
          "wareki",
          "eras",
          "lunar_calendar",
          "data_version"
        ],
        "properties": {
          "year": {
            "type": "integer"
          },
          "wareki": {
            "type": "string",
            "description": "例: 令和8年・「昭和64年・平成元年」"
          },
          "eras": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/YearEra"
            }
          },
          "lunar_calendar": {
            "type": "boolean",
            "description": "旧暦を使っていた年か（1868〜1872年は true）"
          },
          "data_version": {
            "type": "string",
            "format": "date"
          },
          "note": {
            "type": "string",
            "description": "注意書き（1868〜1872年だけ）"
          }
        }
      },
      "EraYear": {
        "type": "object",
        "required": [
          "year",
          "label",
          "seireki",
          "from",
          "to",
          "lunar_calendar"
        ],
        "properties": {
          "year": {
            "type": "integer",
            "minimum": 1
          },
          "label": {
            "type": "string"
          },
          "seireki": {
            "type": "integer",
            "description": "その和暦の年が始まった西暦の年"
          },
          "from": {
            "type": "string",
            "format": "date",
            "description": "その和暦の年の最初の日"
          },
          "to": {
            "type": "string",
            "format": "date",
            "description": "その和暦の年の最後の日"
          },
          "lunar_calendar": {
            "type": "boolean"
          }
        }
      },
      "EraYears": {
        "type": "object",
        "required": [
          "era",
          "years",
          "data_version"
        ],
        "properties": {
          "era": {
            "$ref": "#/components/schemas/Era"
          },
          "years": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EraYear"
            }
          },
          "data_version": {
            "type": "string",
            "format": "date"
          }
        }
      },
      "Meta": {
        "type": "object",
        "properties": {
          "data_version": {
            "type": "string",
            "format": "date"
          },
          "checked_at": {
            "type": "string",
            "format": "date"
          },
          "range": {
            "type": "object",
            "properties": {
              "from": {
                "type": "integer"
              },
              "to": {
                "type": "integer"
              }
            }
          },
          "scope": {
            "type": "string"
          },
          "eras": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "meiji",
                "taisho",
                "showa",
                "heisei",
                "reiwa"
              ]
            }
          },
          "counts": {
            "type": "object",
            "properties": {
              "eras": {
                "type": "integer"
              },
              "years": {
                "type": "integer"
              }
            }
          },
          "sources": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Source"
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "status": {
                "type": "integer"
              },
              "code": {
                "type": "string",
                "enum": [
                  "invalid_path",
                  "region_not_allowed",
                  "year_not_found",
                  "method_not_allowed"
                ]
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}
