images.nasa.

gov API Documentation

Release v1.5.3 (2019­04­18)

API Reference
The im ages.nasa.go v API is o rganized aro und REST. Our API has predictable, reso urce­o riented URLs, and uses HTTP respo nse
co des to  indicate API erro rs. We use built­in HTTP features, like HTTP authenticatio n and HTTP verbs, which are understo o d by
o ff­the­shelf HTTP clients. We suppo rt cro ss­o rigin reso urce sharing, allo wing yo u to  interact securely with o ur API fro m  a client­
side web applicatio n. JSON is returned by all API respo nses, including erro rs.

Each o f the endpo ints described belo w also  co ntains exam ple snippets which use the curl co m m and­line to o l, Unix pipelines, and

the pytho n co m m and­line to o l to  o utput API respo nses in an easy­to ­read fo rm at. We insert superfluo us newlines to  im pro ve
readability in these inline exam ples, but to  run o ur exam ples yo u m ust rem o ve these newlines.

API Root:

https://images-api.nasa.gov

API Endpoints:

/search
/asset/{nasa_id}
/m etadata/{nasa_id}
/captio ns/{nasa_id}
/album /{album _nam e}

Errors
im ages­api.nasa.go v uses co nventio nal HTTP respo nse co des to  indicate the success o r failure o f an API request. In general, co des
in the 2xx range indicate success, co des in the 4xx range indicate an erro r that failed given the info rm atio n pro vided (e.g., a
required param eter was o m itted, a search failed, etc.), and co des in the 5xx range indicate an erro r with o ur API servers (these are
rare).

Mo st erro r respo nses co ntain a reason attribute, a hum an­readable m essage pro viding m o re details abo ut the erro r.

HTTP status code summary

Code Explanation
200 ­ OK Everything wo rked as expected.
400 ­ Bad Request The request was unacceptable, o ften due to  m issing a required
param eter.
404 ­ No t Fo und The requested reso urce do esn’t exist.
500, 502, 503, 504 ­ Server Erro rs So m ething went wro ng o n the API’s end. (These are rare.)

Handling errors
Our API returns HTTP erro r respo nses fo r m any reaso ns, such as a failed search query, invalid param eters, a query fo r a no n­
existent m edia asset, and netwo rk unavailability. We reco m m end writing co de that gracefully handles all po ssible HTTP status
co des o ur API returns.
Performing a search
GET /search?q={q}

Parameters:

Name Type Description

q (o ptio nal) string Free text search term s to  co m pare to  all indexed m etadata.
center (o ptio nal) string NASA center which published the m edia.
descriptio n string Term s to  search fo r in “Descriptio n” fields.
(o ptio nal)
descriptio n_508 string Term s to  search fo r in “508 Descriptio n” fields.
(o ptio nal)
keywo rds (o ptio nal) string Term s to  search fo r in “Keywo rds” fields. Separate m ultiple values with co m m as.
lo catio n (o ptio nal) string Term s to  search fo r in “Lo catio n” fields.
m edia_type string Media types to  restrict the search to . Available types: [“im age”, “audio ”]. Separate m ultiple
(o ptio nal) values with co m m as.
nasa_id (o ptio nal) string The m edia asset’s NASA ID.
page (o ptio nal) integer Page num ber, starting at 1, o f results to  get.
pho to grapher string The prim ary pho to grapher’s nam e.
(o ptio nal)
seco ndary_creato r string A seco ndary pho to grapher/video grapher’s nam e.
(o ptio nal)
title (o ptio nal) string Term s to  search fo r in “Title” fields.
year_start (o ptio nal) string The start year fo r results. Fo rm at: YYYY.
year_end (o ptio nal) string The end year fo r results. Fo rm at: YYYY.

Example Request:

At least o ne param eter is required, but all individual param eters are o ptio nal. All param eter values m ust be URL­enco ded. Mo st

HTTP client libraries will take care o f this fo r yo u. Use --data-urlencode to  enco de values using curl:

curl -G https://images-api.nasa.gov/search
--data-urlencode "q=apollo 11"
--data-urlencode "description=moon landing"
--data-urlencode "media_type=image" |
python -m json.tool

The equivalent pre­enco ded request lo o ks m o re typical:

curl "https://images-api.nasa.gov/search
?q=apollo%2011
&description=moon%20landing
&media_type=image" |
python -m json.tool

Example Response:

Search results will co m e in the fo rm  o f Co llectio n+JSON, which co ntains results and info rm atio n abo ut ho w to  retrieve m o re
details abo ut each result:

{
"collection": {
 "href": "https://images-api.nasa.gov/search?q=apollo%2011...",
"items": [
{
"data": [
{
"center": "JSC",
"date_created": "1969-07-21T00:00:00Z",
"description": "AS11-40-5874 (20 July 1969) ---
Astronaut Edwin E. Aldrin Jr., lunar module pilot
of the first lunar landing mission, poses for a
photograph beside the deployed United States flag
during Apollo 11 extravehicular activity (EVA) on
the lunar surface. The Lunar Module (LM) is on the
left, and the footprints of the astronauts are
clearly visible in the soil of the moon. Astronaut
Neil A. Armstrong, commander, took this picture
with a 70mm Hasselblad lunar surface camera. While
astronauts Armstrong and Aldrin descended in the LM
the \"Eagle\" to explore the Sea of Tranquility
region of the moon, astronaut Michael Collins,
command module pilot, remained with the Command and
Service Modules (CSM) \"Columbia\" in lunar
orbit.",
"keywords": [
"APOLLO 11 FLIGHT",
"MOON",
"LUNAR SURFACE",
"LUNAR BASES",
"LUNAR MODULE",
"ASTRONAUTS",
"EXTRAVEHICULAR ACIVITY"
],
"media_type": "image",
"nasa_id": "as11-40-5874",
"title": "Apollo 11 Mission image - Astronaut Edwin Aldrin
poses beside th"
}
],
"href": "https://images-assets.nasa.gov/image/as11-40-5874/collection.json",
"links": [
{
"href": "https://images-assets.nasa.gov/image/as11-40-5874/as11-40-5874~thumb.jpg
"rel": "preview",
"render": "image"
}
]
}
...*99 more objects omitted*...
],
"links": [
{
"href": "https://images-api.nasa.gov/search?q=apollo+11...&page=2",
"prompt": "Next",
"rel": "next"
}
],
"metadata": {
"total_hits": 336
},
"version": "1.0"
}
}
Retrieving a media asset’s manifest
GET /asset/{nasa_id}

Parameters:

Name Type Description

nasa_id string The m edia asset’s NASA ID.

Example Request:

curl https://images-api.nasa.gov/asset/as11-40-5874 |
python -m json.tool

Example Response:

Asset m anifest results will co m e in the fo rm  o f Co llectio n+JSON:

{
"collection": {
"href": "https://images-api.nasa.gov/asset/as11-40-5874",
"items": [
{
"href": "https://images-assets.nasa.gov/image/as11-40-5874/as11-40-5874~orig.jpg"
},
{
"href": "https://images-assets.nasa.gov/image/as11-40-5874/as11‐40‐5874~medium.jpg"
},
{
"href": "https://images-assets.nasa.gov/image/as11-40-5874/as11‐40‐5874~small.jpg"
},
{
"href": "https://images-assets.nasa.gov/image/as11-40-5874/as11‐40‐5874~thumb.jpg"
},
{
"href": "https://images-assets.nasa.gov/image/as11-40-5874/metadata.json"
}
],
"version": "1.0"
}
}

Retrieving a media asset’s metadata location

GET /m etadata/{nasa_id}

Parameters:

Name Type Description

nasa_id string The m edia asset’s NASA ID.

Example Request:

curl https://images-api.nasa.gov/metadata/as11-40-5874 |
python -m json.tool

Example Response:
 {
"location": "https://images-assets.nasa.gov/image/as11-40-5874/metadata.json"
}

Do wnlo ad the JSON file at the lo catio n in the respo nse to  see the asset’s m etadata.

Retrieving a video asset’s captions location

GET /captio ns/{nasa_id}

Parameters:

Name Type Description

nasa_id string The video  asset’s NASA ID.

Example Request:

curl https://images-api.nasa.gov/captions/172_ISS-Slosh |
python -m json.tool

Example Response:

{
"location": "https://images-assets.nasa.gov/video/172_ISS-Slosh/172_ISS-Slosh.srt"
}

Do wnlo ad the VTT o r SRT file at the lo catio n in the respo nse to  see the video ’s captio ns.

Retrieving a media album’s contents

GET /album /album _nam e

Parameters:

Name Type Description

album _nam e string The m edia album ’s nam e (case­sensitive).
page (o ptio nal) integer Page num ber, starting at 1, o f results to  get.

Example Request:

curl https://images-api.nasa.gov/album/apollo |
python -m json.tool

Example Response:

Like search results, album  co ntents will co m e in the fo rm  o f Co llectio n+JSON, which co ntains results and info rm atio n abo ut ho w
to  retrieve m o re details abo ut each m em ber:

{
"collection": {
"href": "https://images-api.nasa.gov/album/apollo",
"items": [
{
"data": [
{
 "nasa_id": "GSFC_20171102_Archive_e000579",
"album": [
"apollo"
],
"keywords": [
"NASA",
"GSFC",
"Space Technology Demo at NASA Wallops"
],
"title": "Space Technology Demo at NASA Wallops",
"media_type": "image",
"date_created": "2017-11-06T00:00:00Z",
"center": "GSFC",
"description": "A Black Brant IX suborbital sounding rocket is launched at 7:
}
],
"href": "https://images-assets.nasa.gov/image/GSFC_20171102_Archive_e000579/colle
"links": [
{
"href": "https://images-assets.nasa.gov/image/GSFC_20171102_Archive_e0005
"rel": "preview",
"render": "image"
}
]
},
...*99 more objects omitted*...
],
"links": [
{
"href": "https://images-api.nasa.gov/album/apollo?page=2",
"prompt": "Next",
"rel": "next"
}
],
"metadata": {
"total_hits": 302
},
"version": "1.0"
}
}