{
  "openapi": "3.1.0",
  "info": {
    "title": "シルギア 日の出・日の入りAPI",
    "version": "1.0.0",
    "description": "登録不要・無料の日の出・日の入りAPI。47都道府県の県庁所在地など（国立天文台「各地のこよみ」と同じ地点）について、2000〜2100年の毎日の日の出・南中・日の入り・南中高度・昼の長さ・月の出・月の南中・月の入りを返します。時刻は日本時間の HH:MM。定義は国立天文台 暦計算室と同じ（日の出入りは太陽の上辺、月の出入りは月の中心が地平線に接する時刻。大気差 35'08\"・標高 0m）。天文計算は NASA JPL の天体暦 DE440s（skyfield）。説明: https://api.shirugear.com/sun/ 。v1 の中では項目を足すことはあっても、名前や意味は変えません（知らない項目は無視してください）。",
    "termsOfService": "https://api.shirugear.com/terms/",
    "contact": {
      "name": "アナライズギア株式会社（シルギア）",
      "url": "https://shirugear.com/contact"
    }
  },
  "servers": [
    {
      "url": "https://api.shirugear.com"
    }
  ],
  "paths": {
    "/sun/v1/{pref}/{year}.json": {
      "get": {
        "summary": "その都道府県の地点の、その年の毎日の日の出・日の入り・月の出・月の入り",
        "operationId": "getSunYear",
        "parameters": [
          {
            "name": "pref",
            "in": "path",
            "required": true,
            "description": "都道府県コード（半角数字2桁。01 北海道〜47 沖縄県）",
            "schema": {
              "type": "string",
              "pattern": "^[0-9]{2}$",
              "examples": [
                "13"
              ]
            }
          },
          {
            "name": "year",
            "in": "path",
            "required": true,
            "description": "西暦の年（半角数字4桁。2000〜2100）",
            "schema": {
              "type": "string",
              "pattern": "^[0-9]{4}$",
              "examples": [
                "2026"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "その年の毎日",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SunYearResponse"
                }
              }
            }
          },
          "400": {
            "description": "URL の形が正しくない（invalid_path）",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "都道府県コードが 01〜47 の外、または年が 2000〜2100 年の外（not_in_range）",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "GET / HEAD 以外（method_not_allowed）",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/sun/v1/meta.json": {
      "get": {
        "summary": "データの版・期間・地点の一覧・定義",
        "operationId": "getSunMeta",
        "responses": {
          "200": {
            "description": "データの版など",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SunMetaResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SunPoint": {
        "type": "object",
        "description": "計算の地点（国立天文台「各地のこよみ」と同じ地点・経緯度。標高 0m）",
        "required": [
          "name",
          "lat",
          "lon",
          "elevation"
        ],
        "properties": {
          "name": {
            "type": "string",
            "examples": [
              "東京"
            ]
          },
          "lat": {
            "type": "number",
            "description": "緯度（度）",
            "examples": [
              35.6581
            ]
          },
          "lon": {
            "type": "number",
            "description": "経度（度）",
            "examples": [
              139.7414
            ]
          },
          "elevation": {
            "type": "number",
            "description": "標高（m）。いつも 0",
            "const": 0
          }
        }
      },
      "SunDay": {
        "type": "object",
        "description": "1日分。時刻はすべてその日（日本時間の0時〜24時）の中の時刻。日付は丸める前の時刻で決めるので、23時59分30秒以降の月の出入り・南中はその日の 24:00 になる",
        "required": [
          "date",
          "sunrise",
          "sun_transit",
          "sunset",
          "sun_altitude",
          "day_length",
          "moonrise",
          "moon_transit",
          "moonset"
        ],
        "properties": {
          "date": {
            "type": "string",
            "format": "date",
            "examples": [
              "2026-01-01"
            ]
          },
          "sunrise": {
            "type": "string",
            "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$",
            "description": "日の出（太陽の上辺が地平線に接する時刻）"
          },
          "sun_transit": {
            "type": "string",
            "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$",
            "description": "太陽の南中（真南に来る時刻）"
          },
          "sunset": {
            "type": "string",
            "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$",
            "description": "日の入り（太陽の上辺が地平線に接する時刻）"
          },
          "sun_altitude": {
            "type": "number",
            "description": "南中のときの太陽の高度（度・小数1桁。大気差を含む見かけの高度）",
            "examples": [
              31.4
            ]
          },
          "day_length": {
            "type": "string",
            "pattern": "^[0-9]{2}:[0-5][0-9]$",
            "description": "昼の長さ（sunset − sunrise。時間:分）",
            "examples": [
              "09:47"
            ]
          },
          "moonrise": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^(([01][0-9]|2[0-3]):[0-5][0-9]|24:00)$",
            "description": "月の出（月の中心が地平線に接する時刻）。その日に無ければ null"
          },
          "moon_transit": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^(([01][0-9]|2[0-3]):[0-5][0-9]|24:00)$",
            "description": "月の南中。その日に無ければ null"
          },
          "moonset": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^(([01][0-9]|2[0-3]):[0-5][0-9]|24:00)$",
            "description": "月の入り（月の中心が地平線に接する時刻）。その日に無ければ null"
          }
        }
      },
      "SunYearResponse": {
        "type": "object",
        "required": [
          "pref",
          "pref_name",
          "point",
          "year",
          "days",
          "data_version"
        ],
        "properties": {
          "pref": {
            "type": "string",
            "pattern": "^[0-9]{2}$",
            "description": "都道府県コード（JIS X 0401）",
            "examples": [
              "13"
            ]
          },
          "pref_name": {
            "type": "string",
            "examples": [
              "東京都"
            ]
          },
          "point": {
            "$ref": "#/components/schemas/SunPoint"
          },
          "year": {
            "type": "integer",
            "examples": [
              2026
            ]
          },
          "days": {
            "type": "array",
            "description": "1月1日〜12月31日の毎日（365件。うるう年は366件）",
            "items": {
              "$ref": "#/components/schemas/SunDay"
            }
          },
          "data_version": {
            "type": "string",
            "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
            "description": "データの版（元データが変わった日。祝日・営業日API・暦APIと共通）"
          }
        }
      },
      "SunMetaResponse": {
        "type": "object",
        "required": [
          "data_version",
          "built_at",
          "from",
          "to",
          "sources",
          "definitions",
          "points",
          "counts"
        ],
        "properties": {
          "data_version": {
            "type": "string",
            "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"
          },
          "built_at": {
            "type": "string",
            "format": "date-time",
            "description": "データを作った日時（ISO 8601・UTC）"
          },
          "from": {
            "type": "integer",
            "examples": [
              2000
            ]
          },
          "to": {
            "type": "integer",
            "examples": [
              2100
            ]
          },
          "sources": {
            "type": "object",
            "required": [
              "astronomy"
            ],
            "properties": {
              "astronomy": {
                "type": "string",
                "examples": [
                  "JPL DE440s / skyfield 1.55"
                ]
              }
            }
          },
          "definitions": {
            "type": "object",
            "description": "定義（説明文。言い回しは変わることがある）",
            "additionalProperties": {
              "type": [
                "string",
                "number"
              ]
            }
          },
          "points": {
            "type": "array",
            "items": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/SunPoint"
                },
                {
                  "type": "object",
                  "required": [
                    "pref",
                    "pref_name"
                  ],
                  "properties": {
                    "pref": {
                      "type": "string"
                    },
                    "pref_name": {
                      "type": "string"
                    }
                  }
                }
              ]
            }
          },
          "counts": {
            "type": "object",
            "required": [
              "points",
              "years",
              "days"
            ],
            "properties": {
              "points": {
                "type": "integer",
                "examples": [
                  47
                ]
              },
              "years": {
                "type": "integer",
                "examples": [
                  101
                ]
              },
              "days": {
                "type": "integer"
              }
            }
          }
        }
      },
      "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_path",
                  "not_in_range",
                  "not_found",
                  "method_not_allowed"
                ]
              },
              "message": {
                "type": "string",
                "description": "説明文（言い回しは変わることがある）"
              }
            }
          }
        }
      }
    }
  }
}