OpenAPI Specification
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).
'