openapi: 3.0.3
info:
  title: NASA Astronomy Picture of the Day (APOD) API
  description: >-
    The Astronomy Picture of the Day (APOD) API provides access to NASA's
    popular APOD service, returning the astronomy picture or video of the day
    along with a brief explanation written by a professional astronomer.
  version: 1.0.0
  contact:
    name: NASA API Support
    url: https://api.nasa.gov
servers:
  - url: https://api.nasa.gov
paths:
  /planetary/apod:
    get:
      operationId: getApod
      summary: NASA Get Astronomy Picture of the Day
      description: >-
        Returns the astronomy picture of the day. Can retrieve a specific
        date, a date range, or random images.
      parameters:
        - name: api_key
          in: query
          required: true
          description: API key for authentication. Use DEMO_KEY for testing.
          schema:
            type: string
            default: DEMO_KEY
        - name: date
          in: query
          required: false
          description: The date of the APOD image to retrieve (YYYY-MM-DD).
          schema:
            type: string
            format: date
        - name: start_date
          in: query
          required: false
          description: The start of a date range for multiple APOD images.
          schema:
            type: string
            format: date
        - name: end_date
          in: query
          required: false
          description: The end of a date range. Defaults to today.
          schema:
            type: string
            format: date
        - name: count
          in: query
          required: false
          description: Return a specified number of random APOD images.
          schema:
            type: integer
        - name: thumbs
          in: query
          required: false
          description: Return URL of video thumbnail if media type is video.
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ApodImage'
                  - type: array
                    items:
                      $ref: '#/components/schemas/ApodImage'
        '400':
          description: Bad request
        '403':
          description: Forbidden - invalid API key
      tags:
        - Planetary
components:
  schemas:
    ApodImage:
      type: object
      properties:
        date:
          type: string
          format: date
          description: The date of the APOD image.
        explanation:
          type: string
          description: Explanation of the image by a professional astronomer.
        hdurl:
          type: string
          format: uri
          description: URL of the high-resolution image.
        media_type:
          type: string
          enum:
            - image
            - video
          description: The type of media returned.
        service_version:
          type: string
          description: The service version.
        title:
          type: string
          description: Title of the APOD image.
        url:
          type: string
          format: uri
          description: URL of the image or video.
        copyright:
          type: string
          description: Copyright holder of the image, if not public domain.
        thumbnail_url:
          type: string
          format: uri
          description: URL of the video thumbnail (if applicable).
tags:
  - name: Planetary