Protected Data Sources

The download_data function from amadeus provides access to a variety of publicly available environmental data sources. Although publicly available, certain data sources are protected and require users to provide login credentials before accessing and downloading the data. Datasets from the National Aeronautics and Space Administration (NASA), for example, require users to have and provide credentials for a NASA EarthData account.

Motivation

This vignette will demonstrate how to create a NASA EarthData Account, generate a personal access token, and configure amadeus to authenticate automatically using that token.

NASA EarthData Account

Visit https://urs.earthdata.nasa.gov/ to register for or log into a NASA EarthData account.

Account registration provides access to NASA’s Earth Observing System Data and Information System (EOSDIS) and its twelve Distributed Active Archive Centers (DAAC), including:

Alaska Satellite Facility (ASF) DAAC
Atmospheric Science Data Center (ASDC)
Crustal Dynamics Data Information System (CDDIS)
Global Hydrometeorology Resource Center (GHRC)
Goddard Earth Sciences Data and Information Services Center (GES DISC)
Land Processes DAAC (LP DAAC)
Level 1 and Atmosphere Archive and Distribution System (LAADS) DAAC
National Snow and Ice Data Center (NSIDC) DAAC
Oak Ridge National Laboratory (ORNL) DAAC
Ocean Biology DAAC (OB.DAAC)
Physical Oceanography DAAC (PO.DAAC)
Socioeconomic Data and Applications Center (SEDAC)

https://www.earthdata.nasa.gov/centers for more information.

Approved applications

After creating an account, navigate to “My Profile” (https://urs.earthdata.nasa.gov/profile), and then to “Applications > Authorized Apps”. This “Authorized Apps” page specifies which NASA EarthData applications can use your login credentials. For this example, ensure that authorization is enabled for “SEDAC Website”, “SEDAC Website (Alpha)”, and “SEDAC Website (Beta)”.

Generating a NASA EarthData Token

With a NASA EarthData account set up and the required applications authorized, generate a personal access token to use with amadeus.

Log in to https://urs.earthdata.nasa.gov/
Navigate to “My Profile” → “Generate Token”
Click “Generate Token” and copy the resulting token string

Tokens expire after 90 days. Repeat these steps to generate a new token when needed.

Setting Up Authentication in R

amadeus provides setup_nasa_token() to securely store your token so it is available in every R session without ever appearing in scripts or version-controlled files.

Recommended: persist in `~/.Renviron`

# Interactively prompts for the token, then writes to ~/.Renviron
setup_nasa_token(method = "renviron")

After running this command, restart R (or run readRenviron("~/.Renviron")) for the environment variable NASA_EARTHDATA_TOKEN to take effect. Subsequent R sessions will pick up the token automatically.

Alternatively, pass the token directly:

setup_nasa_token(method = "renviron", token = "your_token_here")

Save to a token file

# Saves token to ~/.nasa_earthdata_token (permissions set to user-only)
setup_nasa_token(method = "file", token = "your_token_here")

Pass the file path to individual download functions:

download_data(
  dataset_name = "sedac_population",
  year = "2020",
  data_format = "GeoTIFF",
  data_resolution = "60 minute",
  directory_to_save = "./sedac_population",
  acknowledgement = TRUE,
  nasa_earth_data_token = "~/.nasa_earthdata_token"
)

Current session only

# Sets the token for the current R session only (lost on exit)
setup_nasa_token(method = "session", token = "your_token_here")

Or set the environment variable manually:

Sys.setenv(NASA_EARTHDATA_TOKEN = "your_token_here")

How `amadeus` Uses the Token

All NASA download functions (MERRA-2, MODIS, GEOS-CF, SEDAC population, SEDAC groads) call get_token() internally. The lookup priority is:

NASA_EARTHDATA_TOKEN environment variable (set via ~/.Renviron or Sys.setenv()) — recommended
File path passed as nasa_earth_data_token argument
Token string passed directly as nasa_earth_data_token argument (not recommended for scripts)

Once the token is configured in ~/.Renviron, no extra arguments are needed:

# NASA_EARTHDATA_TOKEN is read automatically from the environment
download_data(
  dataset_name = "sedac_population",
  year = "2020",
  data_format = "GeoTIFF",
  data_resolution = "60 minute",
  directory_to_save = "./sedac_population",
  acknowledgement = TRUE
)

## Using token from environment variable: NASA_EARTHDATA_TOKEN
## Downloading requested files...
## Requested files have been downloaded.
## Unzipping files...
## Files unzipped and saved in ./sedac_population/.

References

EOSDIS Distributed Active Archive Centers (DAAC). National Aeronautics and Space Administration (NASA). Date accessed: January 3, 2024. https://www.earthdata.nasa.gov/centers.
NASA EarthData Token Documentation. National Aeronautics and Space Administration (NASA). https://urs.earthdata.nasa.gov/documentation/for_users/user_token.