Application Development
Launch Your Next Project With NASA
A beginner’s guide to building an application using NASA’s Mars Rover Photo API.
February 18, 2021. Like so many others around the globe, I held my breath, watching, waiting for word from NASA that Perseverance had landed by safely on the surface of Mars. It was only several days later while reading an article about the landing that I realized, by the time NASA received the signal indicating Perseverance’s landing sequence had begun, the Rover had already been on the surface of Mars a full four minutes! Even traveling at the speed of light, it takes each signal sent from Mars an average of 11 minutes to make the journey back to Earth. Fortunately, Perseverance landed safely and continues to further our understanding of the red planet more and more each day.
To that end, NASA created the Mars Rover Photos API to enable developers to build applications showcasing the more than 11,000 images that have been sent back to Earth by Curiosity, Opportunity, Spirit and Perseverance.
To demonstrate the capabilities of the Mars Rover Photos API, I built Postcards from Mars, a minimalist application to showcase the latest images available from each Rover via the API.
Tip: If you’re not familiar with {NASA’s APIs} head to https://api.nasa.gov for all the details and to generate your own API key.
Base URL
All queries to the API start with the base URL https://api.nasa.gov/mars-photos/api/v1 and must include the ?api_key=<YOUR_KEY> param. If you do not have a {NASA API} key, you can use DEMO_KEY or visit the {NASA APIs} page to generate your own.
Latest Photos Endpoint
Postcards from Mars utilizes the latest_photos endpoint to retrieve recent images from a particular Rover by interpolating the Rover name into the query string (/rovers/<ROVER_NAME>/latest_photos).
For example, a GET request sent to https://api.nasa.gov/mars-photos/api/v1/rovers/perseverance/latest_photos?api_key=DEMO_KEY might produce this JSON response.
The image referenced here was taken on the 26th Martian day Perseverance was on Mars (Earth date 2021–03–16) by the SHERLOC WATSON Camera, which are actually two of Perseverance’s science cameras.
SHERLOC: Scanning Habitable Environments with Raman & Luminescence for Organics & Chemicals
WATSON: Wide Angle Topographic Sensor for Operations and eNgineering
The source URL produces this image.
Changing the <ROVER_NAME> (between /rovers/ … /latest_photos) will retrieve the latest images for the specified Rover.
In Postcards from Mars, selecting a different Rover via the dropdown menu sets the selected Rover’s name into state (setRover(newRover)), triggering a new API request for the selected Rover’s latest images. Because ${rover} in the query string is coming from state, the query is automatically updated with the new Rover’s name as the GET request is interpolated.
How I’m Using The API
You may have noticed in the code snippet above that only the img_src of each image is being stored in state. A separate setInterval() method generates a random number selection (randomInt) from the data array and sets the selected image URL (setBackgroundImgUrl()) as the current image. This URL is then passed to the landing container component as a prop imgObj={backgroundImgUrl} and Styled Components renders it as the background image of the <div>. This process repeats every seven seconds, causing the random image rotation in the application.
Mission Manifest Endpoint
To illustrate the wealth of data available, add /manifests/<ROVER_NAME> to the base URL to retrieve detailed information about each Rover’s mission. The endpoint is designed to help narrow down image queries, and includes information such as:
- name (Rover’s name)
- landing_date (Rover’s landing date on Mars)
- launch_date (Rover’s launch date from Earth)
- status (Rover’s mission status)
- max_sol (The most recent Martian sol from which images exist)
- max_date (The most recent Earth date from which images exist)
- total_photos (Total number of images taken by the Rover)
The mission manifest also includes a list of objects under photos which are grouped by sol, and contain the following:
- sol (Martian sol of the Rover’s mission)
- total_photos (Total number of images taken by the Rover on that sol)
- cameras (Cameras for which there are images by that Rover on that sol)
An example JSON response might look like this.
Based on this response, Perseverance has sent back 4,210 total_photos. The max_sol (or Martian day counting up from the day Perseverance landed on Mars) is 26, while the max_date (max Earth date) is 2021–03–16. Under photos, Perseverance sent back 201 total_photos its second day on the planet, along with a list of the cameras that took those images.
Photo Endpoint
You can query all images from each Rover separately via the /rovers/<ROVER_NAME>/photos endpoint. Images in the database are stored by the sol on which they were taken, counting up from the Rover’s landing date on Mars.
Searching by Martian Sol
A sol can range from 0 (the Rover’s landing date on Mars) to the maximum in the database (available via the mission manifest endpoint). To search for images from a specific sol, add the sol=<SOL_VALUE> param after ?api_key=<YOUR_KEY>.
For example, a GET request sent to https://api.nasa.gov/mars-photos/api/v1/rovers/curiosity/photos?api_key=DEMO_KEY&sol=1000 might produce this JSON response.
Searching by Earth Date
To search by Earth date (instead of sol), use the date=<YYYY-MM-DD> param. The earliest date available is the landing date of the Rover. The maximum Earth date is available via the mission manifest endpoint.
Tip: Earth dates may not correspond exactly 1-for-1 with sols because Mars’ solar day is approximately 40 minutes longer than Earth’s.
Filtering by Camera
To filter image queries for a Rover by a specific camera, use the camera=<CAMERA_ABBREVIATION> param.
For example, ?api_key=DEMO_KEY&camera=fhaz.
Each Rover has a different combination of cameras and sensors, and each camera has a unique function and perspective. More information about each Rover’s capabilities is available at https://mars.nasa.gov.
Tip: The camera abbreviation parameter is not case sensitive, however, it must be one of the camera abbreviations available for each respective Rover.
Perseverance
Other Rovers
Tip: Queries that return more than 25 images will be split into several pages. Individual pages can be accessed by adding the
page=<PAGE_NUMBER>param.
API Rate Limits
While NASA does not require authentication in order to explore NASA data, a {NASA API} key is recommended if you will be using {NASA’s APIs} to support a deployed application. Rate limits may vary by service, but the defaults are:
- Hourly limit: 1,000 requests per hour (applied across all api.nasa.gov requests)
Exceeding these limits will cause your API key to be temporarily blocked for 60 minutes.
DEMO_KEY Rate Limits
NASA’s DEMO_KEY can be used for initial exploration of the information available, but has much lower rate limits, so signup for your own API key if you plan to use the service (it’s quick, easy, and free https://api.nasa.gov). The DEMO_KEY rate limits are:
- Hourly Limit: 30 requests per IP address per hour
- Daily Limit: 50 requests per IP address per day
Tip: More information about API rate limits and how to check current usage is available at the {NASA API} website at https://api.nasa.gov.
Countdown to Launch
Now that you have a deeper understanding of how to access the wealth of information and imagery available via the Mars Rover Photos API, the only thing left to do is launch your own application! While Postcards from Mars barely scratches the surface of what is available via the API, I hope this article has helped peak your curiosity and primed your engines with new ideas about how to take advantage of the unique opportunity NASA has created for developers to bring their adventurous spirit to new and exciting applications.
As NASA’s latest Mars Rover tweeted on February 18, 2021:
“… Perseverance will get you anywhere.” @NASAPersevere
Author’s note: This article and the Postcards from Mars application were created to fulfill the requirements of a take home assignment from a potential employer. The application source code is maintained on GitHub. I’m also just a huge nerd and completely fascinated by all of NASA’s recent Mars missions.
