openapi: 3.0.3
info:
  title: NASA Astronomy Picture of the Day () APOD API
  description: 'NASA Astronomy Picture of the Day (APOD) REST API providing daily astronomy images and explanations curated by NASA scientists. Supports retrieval by specific date, date ranges, and random selection, with high-definition image URLs, media type detection, and optional concept tags derived from image metadata. Data is available from 1995-06-16 onward.

    '
  version: 1.0.0
  contact:
    name: NASA API Support
    url: https://api.nasa.gov/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  termsOfService: https://api.nasa.gov/
servers:
- url: https://api.nasa.gov/planetary
  description: NASA API Production Server
security:
- ApiKeyQuery: []
tags:
- name: APOD
  description: Astronomy Picture of the Day endpoints
paths:
  /apod:
    get:
      tags:
      - APOD
      operationId: getApod
      summary: Get Astronomy Picture of the Day
      description: 'Returns the Astronomy Picture of the Day with title, explanation, image URL, HD image URL, media type, copyright, and optional concept tags. Supports date-based filtering, date-range queries, and random image selection. Cannot combine count with date or start_date/end_date.

        '
      parameters:
      - name: api_key
        in: query
        description: 'api.nasa.gov key for expanded usage. Use DEMO_KEY for limited testing (30 requests/hour, 50 requests/day).

          '
        required: false
        schema:
          type: string
          default: DEMO_KEY
          example: DEMO_KEY
      - name: date
        in: query
        description: 'A string in YYYY-MM-DD format indicating the date of the APOD image. Defaults to today''s date. Must be after 1995-06-16, the first day an APOD picture was posted. Cannot be used with count, start_date, or end_date.

          '
        required: false
        schema:
          type: string
          format: date
          example: '2014-10-01'
      - name: start_date
        in: query
        description: 'A string in YYYY-MM-DD format indicating the start of a date range. All images in the range from start_date to end_date will be returned in a JSON array. Cannot be used with date or count.

          '
        required: false
        schema:
          type: string
          format: date
          example: '2017-07-08'
      - name: end_date
        in: query
        description: 'A string in YYYY-MM-DD format indicating the end of a date range. If start_date is specified without an end_date then end_date defaults to the current date. Cannot be used with date or count.

          '
        required: false
        schema:
          type: string
          format: date
          example: '2017-07-10'
      - name: count
        in: query
        description: 'A positive integer, no greater than 100. If specified then count randomly chosen images will be returned in a JSON array. Cannot be used in conjunction with date, start_date, or end_date.

          '
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          example: 5
      - name: concept_tags
        in: query
        description: 'A boolean True|False indicating whether concept tags should be returned with the rest of the response. Concept tags are derived from common search tags associated with the description text. Defaults to False. Note: concept_tags functionality may be disabled in the current service deployment.

          '
        required: false
        schema:
          type: boolean
          default: false
      - name: hd
        in: query
        description: 'A boolean True|False parameter indicating whether or not high-resolution images should be returned. Present for legacy purposes only — it is always ignored by the service and high-resolution URLs are returned regardless.

          '
        required: false
        schema:
          type: boolean
          default: false
      - name: thumbs
        in: query
        description: 'A boolean parameter True|False indicating whether the API should return a thumbnail image URL for video files. If set to True, the API returns URL of video thumbnail. If an APOD is not a video, this parameter is ignored.

          '
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: 'Successful response. Returns a single APOD object when querying by date (or defaulting to today), or a JSON array of APOD objects when using count, start_date/end_date.

            '
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ApodEntry'
                - type: array
                  items:
                    $ref: '#/components/schemas/ApodEntry'
              examples:
                single:
                  summary: Single APOD entry
                  $ref: '#/components/examples/SingleApodEntry'
                multiple:
                  summary: Multiple APOD entries
                  $ref: '#/components/examples/MultipleApodEntries'
        '400':
          description: Bad request — invalid parameters or parameter combination
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                msg: Date must be between Jun 16, 1995 and today.
                code: 400
                service_version: v1
        '404':
          description: No data available for the requested date
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                msg: 'No data available for date: 2020-01-01'
                code: 404
                service_version: v1
        '500':
          description: Internal service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ErrorResponse:
      type: object
      description: Error response returned on bad requests or server errors
      properties:
        msg:
          type: string
          description: Human-readable error message
          example: 'Bad Request: incorrect field passed.'
        code:
          type: integer
          description: HTTP status code
          example: 400
        service_version:
          type: string
          description: The service version that generated the error
          example: v1
    ApodEntry:
      type: object
      description: A single Astronomy Picture of the Day entry
      required:
      - date
      - title
      - explanation
      - url
      - media_type
      - service_version
      properties:
        date:
          type: string
          format: date
          description: Date of the APOD entry in YYYY-MM-DD format
          example: '2014-10-01'
        title:
          type: string
          description: The title of the image or video
          example: Filaments of the Vela Supernova Remnant
        explanation:
          type: string
          description: Detailed explanation of the astronomy picture or video
          example: 'The explosion is over but the consequences continue. About eleven thousand years ago a star in the constellation of Vela could be seen to explode...

            '
        url:
          type: string
          format: uri
          description: The URL of the APOD image or video of the day
          example: https://apod.nasa.gov/apod/image/1310/velafilaments_jadescope_960.jpg
        hdurl:
          type: string
          format: uri
          description: 'The URL for the high-resolution image. Omitted if it does not exist originally at APOD. Not present for video media type.

            '
          example: https://apod.nasa.gov/apod/image/1310/velafilaments_jadescope_2000.jpg
        media_type:
          type: string
          description: 'The type of media returned. Either ''image'' or ''video'' depending on the APOD content.

            '
          enum:
          - image
          - video
          example: image
        service_version:
          type: string
          description: The service version used to fulfill the request
          example: v1
        copyright:
          type: string
          description: 'The name of the copyright holder. Only present if the image is not in the public domain. Absence indicates NASA/public domain.

            '
          example: Panther Observatory
        concepts:
          type: object
          description: 'An ordered dictionary of concepts derived from the APOD explanation text. Only returned when concept_tags=True. May be a string message if concept tagging is disabled in the service.

            '
          additionalProperties:
            type: string
          example:
            '0': Astronomy
            '1': Star
            '2': Sun
            '3': Milky Way
        thumbnail_url:
          type: string
          format: uri
          description: 'The URL of the video thumbnail. Only present when thumbs=True and media_type is ''video''.

            '
          example: https://img.youtube.com/vi/example/0.jpg
        resource:
          type: object
          description: 'A dictionary describing the image_set or planet that the response illustrates, determined by the structured endpoint.

            '
          properties:
            image_set:
              type: string
              example: apod
        concept_tags:
          type: boolean
          description: 'Reflection of the supplied concept_tags option. Included in response because of default values.

            '
          example: false
  examples:
    SingleApodEntry:
      value:
        date: '2014-10-01'
        title: Filaments of the Vela Supernova Remnant
        explanation: 'The explosion is over but the consequences continue. About eleven thousand years ago a star in the constellation of Vela could be seen to explode, creating a strange point of light briefly visible to humans living near the beginning of recorded history.

          '
        url: https://apod.nasa.gov/apod/image/1310/velafilaments_jadescope_960.jpg
        hdurl: https://apod.nasa.gov/apod/image/1310/velafilaments_jadescope_2000.jpg
        media_type: image
        service_version: v1
        concept_tags: 'True'
        concepts:
          '0': Astronomy
          '1': Star
          '2': Sun
          '3': Milky Way
          '4': Hubble Space Telescope
          '5': Earth
          '6': Nebula
          '7': Interstellar medium
    MultipleApodEntries:
      value:
      - copyright: Panther Observatory
        date: '2006-04-15'
        explanation: 'In this stunning cosmic vista, galaxy M81 is on the left surrounded by blue spiral arms. On the right marked by massive gas and dust clouds, is M82.

          '
        hdurl: https://apod.nasa.gov/apod/image/0604/M81_M82_schedler_c80.jpg
        media_type: image
        service_version: v1
        title: 'Galaxy Wars: M81 versus M82'
        url: https://apod.nasa.gov/apod/image/0604/M81_M82_schedler_c25.jpg
      - date: '2013-07-22'
        explanation: 'You are here. Everyone you''ve ever known is here. Every human who has ever lived -- is here.

          '
        hdurl: https://apod.nasa.gov/apod/image/1307/earthmoon2_cassini_946.jpg
        media_type: image
        service_version: v1
        title: Earth and Moon from Saturn
        url: https://apod.nasa.gov/apod/image/1307/earthmoon2_cassini_960.jpg
  securitySchemes:
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: 'NASA API key. Register for a free key at https://api.nasa.gov/#signUp. Use DEMO_KEY for testing (rate limits apply).

        '