Finding NISAR Data with Earthaccess

Earthaccess Python Package¶

earthaccess is a Python library to search for and download or stream NASA Earth science data with just a few lines of code.

Install¶

The latest release of earthaccess can be installed via pip:

python -m pip install earthaccess

or via conda:

conda install -c conda-forge earthaccess

earthaccess is a highly active, open-source, and community-driven library. As such, we recommend using the latest release of the package whenever possible. You can update your installation of earthaccess via pip with:

python -m pip install --upgrade earthaccess

or via conda with:

conda update earthaccess

Search for NISAR data¶

To search for a specific product type, provide the corresponding short name from Table 1 as the short_name parameter. For example, to find a single GCOV product, use the following Python code:

import earthaccess

results = earthaccess.search_data(
    short_name='NISAR_L2_GCOV_BETA_V1',
    count=1
)

For a description of NISAR’s data product types, see Data Products Overview. You can also refine your search by setting time bounds using the temporal= parameter, or by providing an area or region of interest geometry.

Download NISAR data¶

Downloading (or streaming) NISAR data requires logging in with your Earthdata Login (EDL) account. To learn more about EDL, see Accessing Data Using EDL Accounts.

Use the earthaccess.login method to log in. By default, this will look for a .netrc, then for environment variables, and finally prompt you to enter your username and password. For more details and alternatives, please see the earthaccess Authentication guide.

Once logged in, you can download products from your search results:

auth = earthaccess.login()

files = earthaccess.download(results, local_path='.')

Stream NISAR data¶

earthaccess also supports streaming data into memory. NISAR data is hosted in the AWS us-west-2 region and typically served to users through HTTPS CloudFront URLs, or if you are accessing the data from the same region (e.g., a resource in AWS us-west-2), you may also use AWS S3 URIs if you obtain temporary S3 access keys. You can stream data through either HTTPS or S3 protocols, but S3 will be faster and will allow you to use AWS S3-aware tools (e.g., the AWS CLI, boto3, or s3fs).

Similar to downloading, streaming requires logging in with your Earthdata Login (EDL) account. Once logged in, you can use earthaccess.open to create file-like objects via fsspec, which can be used like a file path to stream data. For example:

auth = earthaccess.login()

file_objects = earthaccess.open(results)

opens file objects for each data link in results. A file object can be passed to tools like xarray using the h5netcdf reader:

import xarray as xr

ds = xr.open_datatree(
    file_objects[0],
    engine='h5netcdf',
    decode_timedelta=False,
    phony_dims="access"
)

earthaccess.open will use sensible defaults to provide good performance across all NASA data. You can override these default to fine-tune steaming performance for your access pattern. The next two examples show how to use a specific protocol and set fsspec options.

Example: Stream via HTTPS¶

This end-to-end example searches for a single NISAR GCOV product, retrieves its HTTPS access URL, sets a custom fsspec configuration, and opens it with xarray using the h5netcdf engine.

import earthaccess
import xarray as xr

auth = earthaccess.login()

results = earthaccess.search_data(
    short_name='NISAR_L2_GCOV_BETA_V1',
    count=1
)

https_links = results[0].data_links(access='external')

fsspec_config = {
    'cache_type': 'background',
    'block_size': 16*1024*1024,  # 16 MB
}

fs = earthaccess.get_fsspec_https_session()
ds = xr.open_datatree(
   fs.open(https_links[0], **fsspec_config),
   engine='h5netcdf',
   decode_timedelta=False,
   phony_dims="access"
)

Example: Stream via S3¶

This end-to-end example searches for a single NISAR GCOV product, retrieves its S3 access URI, sets a custom fsspec configuration, and opens it with xarray using the h5netcdf engine. Behind the scenes, earthaccess will request temporary AWS credentials for you, which is described in S3 Access Overview.

import earthaccess
import xarray as xr

auth = earthaccess.login()

results = earthaccess.search_data(
    short_name='NISAR_L2_GCOV_BETA_V1',
    count=1
)

s3_links = results[0].data_links(access='direct')

fsspec_config = {
    'cache_type': 'background',
    'block_size': 16*1024*1024,  # 16 MB
}

endpoint = 'https://nisar.asf.earthdatacloud.nasa.gov/s3credentials'
fs = earthaccess.get_s3_filesystem(endpoint=endpoint)
ds = xr.open_datatree(
   fs.open(s3_links[0], **fsspec_config),
   engine='h5netcdf',
   decode_timedelta=False,
   phony_dims="access"
)