Using the AρρEEARS API in a Landsat ARD Workflow - Getting Started


The intent of this tutorial is to familiarize Landsat Analysis Ready Data (ARD) users with the AρρEEARS application programming interface (API) with demonstrations on how the API, and the services it provides, can be leveraged in an analysis workflow.

Use Case

This tutorial was developed using a real-world use case for a project being completed by the NASA DEVELOP Node at the Marshall Space Flight Center. NASA Develop is a program aimed at integrating NASA Earth observations with society to foster future innovation and cultivate the professionals of tomorrow by addressing diverse environmental issues today.

The example use case comes from a project titled, "Utilizing NASA Earth Observations to Assess Coastline Replenishment Initiatives and Shoreline Risk along Delaware's Coasts". The group is partnering with the Delaware Department of Natural Resources and Environmental Control, Division of Watershed Stewardship for this project. The goals for the project include to identify areas of current and potential shoreline loss along the coast of Delaware, assess the current restoration efforts, and create time-series coastline maps.

Example: Submit an AppEEARS area request for a portion of the Delaware coast along the Prime Hook National Wildlife Refuge to extract Landsat Analysis Ready Data for the years before and after Hurricane Sandy. The outputs will be used to generate false color composite time series to visualize changes to the coastline during the time period.

AρρEEARS Information

To access AρρEEARS, visit:

For comprehensive documentation of the full functionality of the AρρEEARS API, please see the AρρEEARS API Documentation:

Throughout the exercise, specific sections of the API documentation can be accessed by clicking the hyperlinked text.

Setup and Dependencies

It is recommended to use Conda, an environment manager to set up a compatible Python environment. Download Conda for your OS here: Once you have Conda installed, Follow the instructions below to successfully setup a Python environment on MacOS or Windows.

This Python Jupyter Notebook tutorial has been tested using Python versions 3.6, 3.6.6 and 3.7.

Conda was used to create the python environment.

  • Option 1: Download the environment yml file:
    • Open the environment.yml file and change the prefix (last line) to the directory on your OS where you want to create the environment (ex: C:\Username\Anaconda3\envs\ardtutorial) and save the environment file.
    • Using Command Prompt, Anaconda Prompt, Cmder, Terminal, or your preferred command line interface, navigate to the directory where you saved the environment.yml file.
    • Type conda env create -f environment.yml
    • Type activate ardtutorial
  • Option 2: Download each package separately
    • Windows OS or macOS conda create -n ardtutorial python=3.6
  • If you already had conda installed on your OS, it is recommended that you update to the latest version:
    conda update -n base -c defaults conda
  • Required Python packages were installed from the conda-forge channel. Installing packages from the conda-forge channel is done by adding conda-forge to your channels with:
    conda config --add channels conda-forge
  • Activate the newly created environment using the command: activate ardtutorial
  • Required packages needed for this exercise are listed below.
    • requests
      conda install requests
    • pandas
      conda install pandas
    • geopandas
      conda install geopandas
    • xarray
      conda install xarray
    • numpy
      conda install numpy
    • netcdf4
      conda install netcdf4
    • holoviews
      conda install holoviews
    • pyviz   NOTE - PyViz is installed using the pyviz channel not conda-forge.
      conda install -c pyviz hvplot

      If you encounter an issue downloading hvplot using conda, try pip install pyviz hvplot

Next, download the Jupyter Notebook and example shapefile to get started.

1. Getting Started

If this is your first time using the AρρEEARS API, you must first enable API access by following the instructions provided below after signing in with your NASA Earthdata Login.

1.1 Enable Access to the API

To enable access to the AρρEEARS API, navigate to the AρρEEARS website. Click the Sign In button in the top right portion of the AρρEEARS landing page screen.

Once you are signed in, click the Manage User icon in the top right portion of the AρρEEARS landing page screen and select Settings.

Select the Enable API box to gain access to the AρρEEARS API.

1.2 Login to AρρEEARS/Earthdata

To submit a request, you must first login to the AρρEEARS API using your Earthdata login credentials. We’ll use the getpass package to conceal our Earthdata login username and password. When executed, the code below will prompt you to enter your username followed by your password and store them as variables.

Import the required packages and set the input/working directory to run this Jupyter Notebook locally.

In [1]:
# Import required Python packages
import requests
import getpass
import time
import os
import cgi
import json
import pandas as pd
import geopandas as gpd
import xarray
import numpy as np
import hvplot.xarray
import holoviews as hv