{
 "openapi": "3.0.3",
 "info": {
  "title": "SkyDrgn Almanac API",
  "version": "2.3.1",
  "description": "Положения Солнца, Луны, планет и звёзд, астрономические события."
 },
 "servers": [
  {
   "url": "https://skydrgn.site"
  }
 ],
 "paths": {
  "/api/v1/status": {
   "get": {
    "summary": "Состояние сервиса",
    "operationId": "status",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Успешный ответ",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Неверный параметр",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Превышен лимит запросов",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/time": {
   "get": {
    "summary": "Время: UTC, юлианская дата, звёздное время",
    "operationId": "time",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Успешный ответ",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Неверный параметр",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Превышен лимит запросов",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/locations": {
   "get": {
    "summary": "Города с координатами и часовым поясом",
    "operationId": "locations",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Успешный ответ",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Неверный параметр",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Превышен лимит запросов",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/sun": {
   "get": {
    "summary": "Положение Солнца, восход, закат и сумерки",
    "operationId": "sun",
    "parameters": [
     {
      "name": "city",
      "in": "query",
      "required": false,
      "description": "Идентификатор города из /api/v1/locations",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "lat",
      "in": "query",
      "required": false,
      "description": "Широта, от −90 до 90",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "lon",
      "in": "query",
      "required": false,
      "description": "Долгота, от −180 до 180",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "tz",
      "in": "query",
      "required": false,
      "description": "Смещение от UTC в часах, по умолчанию оценивается по долготе",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "date",
      "in": "query",
      "required": false,
      "description": "Локальная дата для восхода и заката, YYYY-MM-DD",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "at",
      "in": "query",
      "required": false,
      "description": "Момент времени в UTC, например 2026-12-14T18:00:00Z",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Успешный ответ",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Неверный параметр",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Превышен лимит запросов",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/moon": {
   "get": {
    "summary": "Положение и фаза Луны, ближайшие фазы",
    "operationId": "moon",
    "parameters": [
     {
      "name": "city",
      "in": "query",
      "required": false,
      "description": "Идентификатор города из /api/v1/locations",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "lat",
      "in": "query",
      "required": false,
      "description": "Широта, от −90 до 90",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "lon",
      "in": "query",
      "required": false,
      "description": "Долгота, от −180 до 180",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "tz",
      "in": "query",
      "required": false,
      "description": "Смещение от UTC в часах, по умолчанию оценивается по долготе",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "date",
      "in": "query",
      "required": false,
      "description": "Локальная дата для восхода и заката, YYYY-MM-DD",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "at",
      "in": "query",
      "required": false,
      "description": "Момент времени в UTC, например 2026-12-14T18:00:00Z",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Успешный ответ",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Неверный параметр",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Превышен лимит запросов",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/planets": {
   "get": {
    "summary": "Меркурий, Венера, Марс, Юпитер и Сатурн",
    "operationId": "planets",
    "parameters": [
     {
      "name": "city",
      "in": "query",
      "required": false,
      "description": "Идентификатор города из /api/v1/locations",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "lat",
      "in": "query",
      "required": false,
      "description": "Широта, от −90 до 90",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "lon",
      "in": "query",
      "required": false,
      "description": "Долгота, от −180 до 180",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "tz",
      "in": "query",
      "required": false,
      "description": "Смещение от UTC в часах, по умолчанию оценивается по долготе",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "at",
      "in": "query",
      "required": false,
      "description": "Момент времени в UTC, например 2026-12-14T18:00:00Z",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Успешный ответ",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Неверный параметр",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Превышен лимит запросов",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/stars": {
   "get": {
    "summary": "Каталог ярких звёзд, с фильтром по созвездию",
    "operationId": "stars",
    "parameters": [
     {
      "name": "constellation",
      "in": "query",
      "required": false,
      "description": "Трёхбуквенный код созвездия, например Dra",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "city",
      "in": "query",
      "required": false,
      "description": "Идентификатор города из /api/v1/locations",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "lat",
      "in": "query",
      "required": false,
      "description": "Широта, от −90 до 90",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "lon",
      "in": "query",
      "required": false,
      "description": "Долгота, от −180 до 180",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "min_altitude",
      "in": "query",
      "required": false,
      "description": "Минимальная высота над горизонтом в градусах",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "Сколько записей вернуть",
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "at",
      "in": "query",
      "required": false,
      "description": "Момент времени в UTC, например 2026-12-14T18:00:00Z",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Успешный ответ",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Неверный параметр",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Превышен лимит запросов",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/sky": {
   "get": {
    "summary": "Сводка: Солнце, Луна, планеты и видимые звёзды",
    "operationId": "sky",
    "parameters": [
     {
      "name": "city",
      "in": "query",
      "required": false,
      "description": "Идентификатор города из /api/v1/locations",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "lat",
      "in": "query",
      "required": false,
      "description": "Широта, от −90 до 90",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "lon",
      "in": "query",
      "required": false,
      "description": "Долгота, от −180 до 180",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "tz",
      "in": "query",
      "required": false,
      "description": "Смещение от UTC в часах, по умолчанию оценивается по долготе",
      "schema": {
       "type": "number"
      }
     },
     {
      "name": "date",
      "in": "query",
      "required": false,
      "description": "Локальная дата для восхода и заката, YYYY-MM-DD",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "at",
      "in": "query",
      "required": false,
      "description": "Момент времени в UTC, например 2026-12-14T18:00:00Z",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Успешный ответ",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Неверный параметр",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Превышен лимит запросов",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/events": {
   "get": {
    "summary": "Астрономические события",
    "operationId": "events",
    "parameters": [
     {
      "name": "from",
      "in": "query",
      "required": false,
      "description": "Начальная дата, YYYY-MM-DD",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "type",
      "in": "query",
      "required": false,
      "description": "meteors, eclipse, planet или season",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "Сколько записей вернуть",
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Успешный ответ",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Неверный параметр",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Превышен лимит запросов",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  }
 },
 "components": {
  "schemas": {
   "Error": {
    "type": "object",
    "required": [
     "error"
    ],
    "properties": {
     "error": {
      "type": "object",
      "required": [
       "code",
       "message",
       "request_id"
      ],
      "properties": {
       "code": {
        "type": "string"
       },
       "message": {
        "type": "string"
       },
       "param": {
        "type": "string"
       },
       "request_id": {
        "type": "string"
       }
      }
     }
    }
   }
  }
 }
}