Protected Data Sources

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.

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.

1. Log in to https://urs.earthdata.nasa.gov/
2. Navigate to “My Profile” → “Generate Token”
3. 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.

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

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

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

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"
)

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

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:

1. NASA_EARTHDATA_TOKEN environment variable (set via ~/.Renviron or Sys.setenv()) — recommended
2. File path passed as nasa_earth_data_token argument
3. 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.