openapi: 3.1.0
info:
  title: Astronomy API
  version: "2.0"
  description: |
    AstronomyAPI is a web API for retrieving astronomical information
    including celestial body positions, moon phase imagery, star charts,
    astronomical events, and deep space object search for any geographic
    location and date/time combination.
  contact:
    name: AstronomyAPI
    url: https://astronomyapi.com
servers:
  - url: https://api.astronomyapi.com/api/v2
    description: Astronomy API v2
tags:
  - name: Bodies
    description: Celestial body information and positions
  - name: Events
    description: Astronomical events for a given location and date range
  - name: Studio
    description: Generated imagery (moon phase and star charts)
  - name: Search
    description: Search for stars and deep space objects
paths:
  /bodies:
    get:
      tags: [Bodies]
      summary: List supported celestial bodies
      security:
        - basicAuth: []
      responses:
        "200":
          description: List of celestial bodies
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
  /bodies/positions:
    get:
      tags: [Bodies]
      summary: Get positions of all bodies for an observer
      security:
        - basicAuth: []
      parameters:
        - { name: latitude,  in: query, required: true, schema: { type: number, format: float } }
        - { name: longitude, in: query, required: true, schema: { type: number, format: float } }
        - { name: elevation, in: query, schema: { type: number, format: float } }
        - { name: from_date, in: query, required: true, schema: { type: string, format: date } }
        - { name: to_date,   in: query, required: true, schema: { type: string, format: date } }
        - { name: time,      in: query, required: true, schema: { type: string, examples: ["12:00:00"] } }
        - { name: output,    in: query, schema: { type: string, enum: [rows, table] } }
      responses:
        "200":
          description: Body positions
  /bodies/positions/{body}:
    get:
      tags: [Bodies]
      summary: Get positions of a single body for an observer
      security:
        - basicAuth: []
      parameters:
        - { name: body,      in: path,  required: true, schema: { type: string, examples: [sun, moon, mars] } }
        - { name: latitude,  in: query, required: true, schema: { type: number, format: float } }
        - { name: longitude, in: query, required: true, schema: { type: number, format: float } }
        - { name: elevation, in: query, schema: { type: number, format: float } }
        - { name: from_date, in: query, required: true, schema: { type: string, format: date } }
        - { name: to_date,   in: query, required: true, schema: { type: string, format: date } }
        - { name: time,      in: query, required: true, schema: { type: string } }
      responses:
        "200":
          description: Position data for the body
  /bodies/events/{body}:
    get:
      tags: [Events]
      summary: Get celestial events for a body
      security:
        - basicAuth: []
      parameters:
        - { name: body,      in: path,  required: true, schema: { type: string } }
        - { name: latitude,  in: query, required: true, schema: { type: number, format: float } }
        - { name: longitude, in: query, required: true, schema: { type: number, format: float } }
        - { name: elevation, in: query, schema: { type: number, format: float } }
        - { name: from_date, in: query, required: true, schema: { type: string, format: date } }
        - { name: to_date,   in: query, required: true, schema: { type: string, format: date } }
        - { name: time,      in: query, required: true, schema: { type: string } }
        - { name: type,      in: query, schema: { type: string } }
      responses:
        "200":
          description: Event data
  /studio/moon-phase:
    post:
      tags: [Studio]
      summary: Generate a moon phase image
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                format:
                  type: string
                  enum: [png, svg]
                style:
                  type: object
                observer:
                  type: object
                  properties:
                    latitude:  { type: number }
                    longitude: { type: number }
                    date:      { type: string, format: date }
                view:
                  type: object
                  properties:
                    type:        { type: string, enum: [portrait-simple, landscape-simple] }
                    orientation: { type: string, enum: [north-up, south-up] }
      responses:
        "200":
          description: Image URL returned in payload
  /studio/star-chart:
    post:
      tags: [Studio]
      summary: Generate a star chart image
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                style:
                  type: string
                  enum: [default, inverted, navy, red]
                observer:
                  type: object
                  properties:
                    latitude:  { type: number }
                    longitude: { type: number }
                    date:      { type: string, format: date }
                view:
                  type: object
                  description: View type (area or constellation)
      responses:
        "200":
          description: Star chart image URL
  /search:
    get:
      tags: [Search]
      summary: Search for stars and deep space objects
      security:
        - basicAuth: []
      parameters:
        - { name: term,        in: query, required: true, schema: { type: string } }
        - { name: match_type,  in: query, schema: { type: string, enum: [fuzzy, exact] } }
        - { name: ra,          in: query, schema: { type: number } }
        - { name: dec,         in: query, schema: { type: number } }
        - { name: order_by,    in: query, schema: { type: string } }
        - { name: limit,       in: query, schema: { type: integer } }
        - { name: offset,      in: query, schema: { type: integer } }
      responses:
        "200":
          description: Search results
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: |
        HTTP Basic auth: username is the Application ID and password is the
        Application Secret. The client typically sends
        `Authorization: Basic base64(applicationId:applicationSecret)`.