| Type: | Package |
| Title: | Access National Aeronautics and Space Administration (NASA) APIs |
| Version: | 1.0.0 |
| Author: | Steph Buongiorno [aut, cre] |
| Maintainer: | Steph Buongiorno <steph.buon@proton.me> |
| Description: | Provides functions to access and download data from various NASA APIs https://api.nasa.gov/#browseAPI, including: Astronomy Picture of the Day (APOD), Mars Rover Photos, Earth Polychromatic Imaging Camera (EPIC), Near Earth Object Web Service (NeoWs), Earth Observatory Natural Event Tracker (EONET), and NASA Earthdata CMR Search. Most endpoints require a NASA API key for access. Data is retrieved, cleaned for analysis, and returned in a dataframe-friendly format. |
| License: | GPL-3 |
| Encoding: | UTF-8 |
| Imports: | httr, jsonlite, magick, dplyr |
| RoxygenNote: | 7.3.2 |
| URL: | https://api.nasa.gov, https://eonet.gsfc.nasa.gov, https://cmr.earthdata.nasa.gov:443/search |
| NeedsCompilation: | no |
| Packaged: | 2025-06-02 15:59:03 UTC; steph |
| Repository: | CRAN |
| Date/Publication: | 2025-06-04 15:10:02 UTC |
Retrieve Astronomy Picture of the Day (APOD) images and metadata
Description
Queries NASA's Astronomy Picture of the Day (APOD) API to retrieve images and metadata between a specified start and end date. Only image media types are included.
Usage
get_apod_metadata(
start_date,
end_date,
api_key = "DEMO_KEY",
folder_name = NULL
)
Arguments
start_date |
Character. Start date for the query in "YYYY-MM-DD" format. |
end_date |
Character. End date for the query in "YYYY-MM-DD" format. |
api_key |
Character. NASA API key. Defaults to "DEMO_KEY", but a personal API key is recommended. |
folder_name |
Character or NULL. Folder name to save images on Desktop if provided. If NULL, images are only printed and not saved. |
Details
The function filters out any media types that are not images—for example, videos. It prints the image along with a truncated explanation for each entry, then returns the full metadata as a data frame.
Value
A data frame containing metadata about the APOD images (date, title, explanation, URL, and media type).
Examples
## Not run:
# Retrieve APOD images for a date range
apod_metadata <- get_apod_metadata(
start_date = "2024-04-01",
end_date = "2024-04-02",
api_key = "DEMO_KEY"
)
## End(Not run)
Search NASA Earthdata Collections Metadata
Description
Queries NASA's Common Metadata Repository (CMR) to search Earth science datasets related to a specified keyword. Optionally filters results by a temporal range.
Usage
get_earthdata(keyword, n_results, start_date = NULL, end_date = NULL)
Arguments
keyword |
Character. A search term or phrase used to find relevant datasets in titles, descriptions, keywords, and provider names. |
n_results |
Integer. The number of dataset entries to retrieve. If more than 2000, multiple pages will be requested automatically. |
start_date |
Character or NULL. Optional start date filter in "YYYY-MM-DD" format.
If provided, must be used with |
end_date |
Character or NULL. Optional end date filter in "YYYY-MM-DD" format.
If provided, must be used with |
Details
CMR is the Earthdata search engine, the backend database that stores metadata about:
- Satellite datasets - Earth science data (climate, ocean, atmosphere, land) - Observational granules (single files like images, temperature readings, etc.) - Services (subsetting, reformatting, and other data services)
The search finds matches based on the keyword provided. The keyword can appear in:
- Dataset titles - Dataset descriptions - Dataset keywords (tags) - Some provider names
The function accesses the CMR API endpoint:
https://cmr.earthdata.nasa.gov/
search/collections.json
(Note: This is an API endpoint and may return an error when opened in a browser.)
It harmonizes columns across API pages and returns up to the number of requested results.
If no results are found, an empty data frame is returned.
Value
A data frame containing metadata about the matching datasets, with only cleaned column names (columns with '.' or '$' removed).
Examples
## Not run:
# Search for 1 dataset related to sea surface temperature
results <- get_earthdata(keyword = "sea surface temperature", n_results = 1)
# Search with a temporal constraint
results_time <- get_earthdata(
keyword = "sea surface temperature",
n_results = 1,
start_date = "2020-01-01",
end_date = "2020-01-02"
)
## End(Not run)
Retrieve and Save EPIC Natural Color Earth Images
Description
Queries NASA's EPIC (Earth Polychromatic Imaging Camera) API to retrieve metadata and images of Earth taken on a specified date. Images can optionally be saved to a folder on the user's Desktop.
Usage
get_epic_earth_images(date = NULL, api_key = "DEMO_KEY", folder_name = NULL)
Arguments
date |
Character or NULL. The Earth date in "YYYY-MM-DD" format to retrieve images from. If NULL, today's date is used. Note that today's images may not yet be available. |
api_key |
Character. NASA API key. Defaults to |
folder_name |
Character or NULL. If provided, images will be saved in a folder with this name on the user's Desktop. If NULL, images are only displayed and not saved. |
Details
The function builds the download URLs based on NASA's EPIC archive structure, which organizes images into
year/month/day subfolders. Only natural color images are retrieved.
Images are displayed using the magick package and can be optionally saved as PNG files.
Value
A data frame containing metadata for the retrieved EPIC images, including image names, dates, and captions.
Examples
## Not run:
# Retrieve and view EPIC images from April 1, 2024
epic_data <- get_epic_earth_images(date = "2024-04-01", api_key = "your_actual_api_key")
# Retrieve and save EPIC images to Desktop/EPIC_Images
epic_data_saved <- get_epic_earth_images(
date = "2024-04-01",
api_key = "DEMO_KEY",
folder_name = "EPIC_Images"
)
## End(Not run)
Retrieve and Save Mars Rover Photos
Description
Queries NASA's Mars Rover Photos API to retrieve photos taken by a specified rover on a given Earth date. Optionally saves the images to a folder on the user's Desktop.
Usage
get_mars_rover_photos_and_metadata(
rover,
earth_date,
api_key = "DEMO_KEY",
folder_name = NULL
)
Arguments
rover |
Character. The name of the Mars rover. Must be one of the following:
|
earth_date |
Character. The Earth date to query in |
api_key |
Character. NASA API key. Defaults to |
folder_name |
Character or NULL. If provided, images will be saved in a folder with this name on the user's Desktop. If NULL, images are only displayed and not saved. |
Details
The function prints each retrieved image and associated metadata to the console. If a folder name is specified, images are saved to the Desktop inside the given folder. Only images taken on the specified date are returned; if no images exist, the function stops with an error.
Value
A data frame containing metadata about the retrieved photos, including photo ID, sol (Martian day), camera name, image source URL, Earth date, and rover name.
Examples
## Not run:
# Retrieve and save photos taken by Curiosity on June 3, 2015
mars_photos_metadata <- get_mars_rover_photos_and_metadata(
rover = "curiosity",
earth_date = "2015-06-03",
api_key = "DEMO_KEY",
folder_name = "MarsPhotos"
)
## End(Not run)