Package: earthaccess
Overviewearthaccessis apython library to search, download or stream NASA Earth science datawith just a few lines of code.In the age of cloud computing, the power of open science only reaches its full potential if we have easy-to-use workflows that facilitate research in an inclusive, efficient and reproducible way. Unfortunately —as it stands today— scientists and students alike face a steep learning curve adapting to systems that have grown too complex and end up spending more time on the technicalities of the tools, cloud and NASA APIs than focusing on their important science.During several workshops organized byNASA Openscapes, the need to provide easy-to-use tools to our users became evident. Open science is a collaborative effort; it involves people from different technical backgrounds, and the data analysis to solve the pressing problems we face cannot be limited by the complexity of the underlying systems. Therefore, providing easy access to NASA Earthdata regardless of the data storage location (hosted within or outside of the cloud) is the main motivation behind this Python library.Installing earthaccessYou will need Python 3.8 or higher installed.Install the latest release using condacondainstall-cconda-forgeearthaccessUsing PippipinstallearthaccessTry it in your browser without installing anything!UsageWithearthaccesswe can login, search and download data with a few lines of code and even more relevant, our code will work the same way if we are running it in the cloud or from our laptop.earthaccesshandles authentication withNASA's Earthdata Login (EDL), search using NASA'sCMRand access throughfsspec.The only requirement to use this library is to open a free account with NASAEDL.AuthenticationBy default,earthaccesswith automatically look for your EDL account credentials in two locations:A~/.netrcfileEARTHDATA_USERNAMEandEARTHDATA_PASSWORDenvironment variablesIf neither of these options are configured, you can authenticate by calling theearthaccess.login()method
and manually entering your EDL account credentials.importearthaccessearthaccess.login()Note you can passpersist=Truetoearthaccess.login()to have the EDL account credentials you enter
automatically saved to a~/.netrcfile for future use.Once you are authenticated with NASA EDL you can:Get a file from a DAAC using afsspecsession.Request temporary S3 credentials from a particular DAAC (needed to download or stream data from an S3 bucket in the cloud).Use the library to download or stream data directly from S3.Regenerate CMR tokens (used for restricted datasets)Searching for dataOnce we have selected our dataset we can search for the data granules usingdoi,short_nameorconcept_id.
If we are not sure or we don't know how to search for a particular dataset, we can start with the"Introducing NASA earthaccess"tutorial or through theNASA Earthdata Search portal. For a complete list of search parameters we can use visit the extendedAPI documentation.results=earthaccess.search_data(short_name='SEA_SURFACE_HEIGHT_ALT_GRIDS_L4_2SATS_5DAY_6THDEG_V_JPL2205',cloud_hosted=True,bounding_box=(-10,20,10,50),temporal=("1999-02","2019-03"),count=10)Now that we have our results we can do multiple things: We can iterate over them to get HTTP (or S3) links, we can download the files to a local folder, or we can open these files and stream their content directly to other libraries e.g. xarray.Accessing the dataOption 1: Using the data linksIf we already have a workflow in place for downloading our data, we can useearthaccessas a search-only library and get HTTP links from our query results. This could be the case if our current workflow uses a different language and we only need the links as input.# if the data set is cloud hosted there will be S3 links available. The access parameter accepts "direct" or "external", direct access is only possible if you are in the us-west-2 region in the cloud.data_links=[granule.data_links(access="direct")forgranuleinresults]# or if the data is an on-prem datasetdata_links=[granule.data_links(access="external")forgranuleinresults]Note:earthaccesscan get S3 credentials for us, or auhenticated HTTP sessions in case we want to use them with a different library.Option 2: Download data to a local folderThis option is practical if you have the necessary space available on disk. Theearthaccesslibrary will print out the approximate size of the download and its progress.files=earthaccess.download(results,"./local_folder")Option 3: Direct S3 Access - Stream data directly to xarrayThis method works best if you are in the same Amazon Web Services (AWS) region as the data (us-west-2) and you are working with gridded datasets (processing level 3 and above).importxarrayasxrfiles=earthaccess.open(results)ds=xr.open_mfdataset(files)And that's it! Just one line of code, and this same piece of code will also work for data that are not hosted in the cloud, i.e. located at NASA storage centers.More examples coming soon!CompatibilityOnlyPython 3.8+is supported.ContributorsContributing GuideWelcome! 😊👋Please see theContributing Guide.Project Board.GlossaryNASA Earth Science GlossaryLicenseearthaccess is licensed under the MIT license. SeeLICENSE.Level of SupportThis repository is not actively supported by NSIDC but we welcome issue submissions and pull requests in order to foster community contribution.