Getting Started with the AρρEEARS API: Submitting and Downloading an Area Request

Tutorial Jupyter Notebok

3 Relevant Products

Tools

Details:

Published: April 28, 2020

Getting Started with the AρρEEARS API: Submitting and Downloading an Area Request

This tutorial demonstrates how to use Python to connect to the AρρEEARS API

The Application for Extracting and Exploring Analysis Ready Samples (AρρEEARS) offers a simple and efficient way to access and transform geospatial data from a variety of federal data archives in an easy-to-use web application interface. AρρEEARS enables users to subset geospatial data spatially, temporally, and by band/layer for point and area samples. AρρEEARS returns not only the requested data, but also the associated quality values, and offers interactive visualizations with summary statistics in the web interface. The AρρEEARS API offers users programmatic access to all features available in AρρEEARS, with the exception of visualizations. The API features are demonstrated in this notebook.

Example: Submit an area request using a U.S. National Park boundary as the region of interest for extracting elevation, vegetation and land surface temperature data

Connect to the AρρEEARS API, query the list of available products, submit an area sample request, download the request, become familiar with the AρρEEARS Quality API, and import the results into Python for visualization. AρρEEARS area sample requests allow users to subset their desired data by spatial area via vector polygons (shapefiles or GeoJSONs). Users can also reproject and reformat the output data. AρρEEARS returns the valid data from the parameters defined within the sample request.

Data Used in the Example:

  • Data layers:
    • NASA MEaSUREs Shuttle Radar Topography Mission (SRTM) Version 3 Digital Elevation Model
    • Combined MODIS Leaf Area Index (LAI)
    • Terra MODIS Land Surface Temperature
      • MOD11A2.061, 1000m, 8 day: 'LST_Day_1km', 'LST_Night_1km'

Topics Covered:

  1. Getting Started
    1a. Set Up the Working Environment
    1b. Login [Login]
  2. Query Available Products [Product API]
    2a. Search and Explore Available Products [List Products]
    2b. Search and Explore Available Layers [List Layers]
  3. Submit an Area Request [Tasks]
    3a. Import a Shapefile
    3b. Search and Explore Available Projections [Spatial API]
    3c. Compile a JSON [Task Object]
    3d. Submit a Task Request [Submit Task]
    3e. Retrieve Task Status [Retrieve Task]
  4. Download a Request [Bundle API]
    4a. Explore Files in Request Output [List Files]
    4b. Download Files in a Request (Automation) [Download File]
  5. Explore AρρEEARS Quality Service [Quality API]
    5a. List Quality Layers [List Quality Layers]
    5b. Show Quality Values [List Quality Values]
    5c. Decode Quality Values [Decode Quality Values]
  6. BONUS: Import Request Output and Visualize
    6a. Import a GeoTIFF
    6b. Plot a GeoTIFF

Dependencies:

AρρEEARS Information:

To access AρρEEARS, visit: https://appeears.earthdatacloud.nasa.gov/

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

Throughout the tutorial, specific sections of the API documentation can be accessed by clicking on the bracketed [] links in the section headings.

Files Used in this Tutorial:

Source Code used to Generate this Tutorial:

1. Getting Started

1a. Set Up the Working Environment

Import the required packages, set the input/working directory, and create an output directory for the results.

# Import packages 
import requests as r
import getpass, pprint, time, os, cgi, json
import geopandas as gpd

If you are missing any of the packages above, download them in order to use the full functionality of this tutorial.

# Set input directory, change working directory
inDir = 'D:/appeears-api-getting-started/'           # IMPORTANT: Update to reflect directory on your OS
os.chdir(inDir)                                      # Change to working directory
api = 'https://appeears.earthdatacloud.nasa.gov/api/'  # Set the AρρEEARS API to a variable
If you plan to execute this tutorial on your own OS, `inDir` above needs to be changed.

1b. Login[Login]

To submit a request, you must first login to the AρρEEARS API. The AρρEEARS API requires the same NASA Earthdata Login as the AρρEEARS user interface. Use the getpass package to enter your NASA Earthdata login Username and Password. When prompted after executing the code block below, enter your username followed by your password.

user = getpass.getpass(prompt = 'Enter NASA Earthdata Login Username: ')      # Input NASA Earthdata Login Username
password = getpass.getpass(prompt = 'Enter NASA Earthdata Login Password: ')  # Input NASA Earthdata Login Password

Enter NASA Earthdata Login Username: ········
Enter NASA Earthdata Login Password: ········

Use the requests package to post your username and password. A successful login will provide you with a token to be used later in this tutorial to submit a request. For more information or if you are experiencing difficulties, please see the API Documentation.

token_response = r.post('{}login'.format(api), auth=(user, password)).json() # Insert API URL, call login service, provide credentials & return json
del user, password                                                           # Remove user and password information
token_response                                                               # Print response

{'token_type': 'Bearer',
'token': 'EXIW5BKOfm6GyO99WnD3Acwexo-JN5cNdlksZcdRB34C9x9kmCVxI34hwyjYKyO3hfXfmHk32ZdrcAg59QVb2Q',
'expiration': '2022-04-06T21:08:05Z'}

Above, you should see a Bearer token. Notice that this token will expire approximately 48 hours after being acquired.

2. Query Available Products [Product API]

2a. Search and Explore Available Products [List Products]

The product API provides details about all of the products and layers available in AρρEEARS. Below, call the product API to list all of the products available in AρρEEARS.

product_response = r.get('{}product'.format(api)).json()                         # request all products in the product service
print('AρρEEARS currently supports {} products.'.format(len(product_response)))  # Print no. products available in AppEEARS

AρρEEARS currently supports 155 products.

Next, create a dictionary indexed by product name, making it easier to query a specific product.

products = {p['ProductAndVersion']: p for p in product_response} # Create a dictionary indexed by product name & version
products['MCD15A3H.006']                                         # Print information for MCD15A3H.006 LAI/FPAR Product

{'Product': 'MCD15A3H',
'Platform': 'Combined MODIS',
'Description': 'Leaf Area Index (LAI) and Fraction of Photosynthetically Active Radiation (FPAR)',
'RasterType': 'Tile',
'Resolution': '500m',
'TemporalGranularity': '4 day',
'Version': '006',
'Available': True,
'DocLink': 'https://doi.org/10.5067/MODIS/MCD15A3H.006',
'Source': 'LP DAAC',
'TemporalExtentStart': '2002-07-04',
'TemporalExtentEnd': 'Present',
'Deleted': False,
'DOI': '10.5067/MODIS/MCD15A3H.006',
'ProductAndVersion': 'MCD15A3H.006'}

The product service provides many useful details, including if a product is currently available in AρρEEARS, a description, and information on the spatial and temporal resolution.

Below, make a list of all product+version names, and search for products containing Leaf Area Index in their description.

prodNames = {p['ProductAndVersion'] for p in product_response} # Make list of all products (including version)
for p in prodNames:                                            # Make for loop to search list of products 'Description' for a keyword                
    if 'Leaf Area Index' in products[p]['Description']:
        pprint.pprint(products[p])                             # Print info for each product containing LAI in its description

{'Available': True,
 'DOI': '10.5067/MODIS/MCD15A3H.006',
 'Deleted': False,
 'Description': 'Leaf Area Index (LAI) and Fraction of Photosynthetically '
                'Active Radiation (FPAR)',
 'DocLink': 'https://doi.org/10.5067/MODIS/MCD15A3H.006',
 'Platform': 'Combined MODIS',
 'Product': 'MCD15A3H',
 'ProductAndVersion': 'MCD15A3H.006',
 'RasterType': 'Tile',
 'Resolution': '500m',
 'Source': 'LP DAAC',
 'TemporalExtentEnd': 'Present',
 'TemporalExtentStart': '2002-07-04',
 'TemporalGranularity': '4 day',
 'Version': '006'}
{'Available': True,
 'DOI': '10.5067/MODIS/MYD15A2H.061',
 'Deleted': False,
 'Description': 'Leaf Area Index (LAI) and Fraction of Photosynthetically '
                'Active Radiation (FPAR)',
 'DocLink': 'https://doi.org/10.5067/MODIS/MYD15A2H.061',
 'Platform': 'Aqua MODIS',
 'Product': 'MYD15A2H',
 'ProductAndVersion': 'MYD15A2H.061',
 'RasterType': 'Tile',
 'Resolution': '500m',
 'Source': 'LP DAAC',
 'TemporalExtentEnd': 'Present',
 'TemporalExtentStart': '2002-07-04',
 'TemporalGranularity': '8 day',
 'Version': '061'}
{'Available': True,
 'DOI': '10.5067/MODIS/MOD15A2H.006',
 'Deleted': False,
 'Description': 'Leaf Area Index (LAI) and Fraction of Photosynthetically '
                'Active Radiation (FPAR)',
 'DocLink': 'https://doi.org/10.5067/MODIS/MOD15A2H.006',
 'Platform': 'Terra MODIS',
 'Product': 'MOD15A2H',
 'ProductAndVersion': 'MOD15A2H.006',
 'RasterType': 'Tile',
 'Resolution': '500m',
 'Source': 'LP DAAC',
 'TemporalExtentEnd': 'Present',
 'TemporalExtentStart': '2000-02-18',
 'TemporalGranularity': '8 day',
 'Version': '006'}
{'Available': True,
 'DOI': '10.5067/MODIS/MCD15A2H.006',
 'Deleted': False,
 'Description': 'Leaf Area Index (LAI) and Fraction of Photosynthetically '
                'Active Radiation (FPAR)',
 'DocLink': 'https://doi.org/10.5067/MODIS/MCD15A2H.006',
 'Platform': 'Combined MODIS',
 'Product': 'MCD15A2H',
 'ProductAndVersion': 'MCD15A2H.006',
 'RasterType': 'Tile',
 'Resolution': '500m',
 'Source': 'LP DAAC',
 'TemporalExtentEnd': 'Present',
 'TemporalExtentStart': '2002-07-04',
 'TemporalGranularity': '8 day',
 'Version': '006'}
{'Available': True,
 'DOI': '10.5067/VIIRS/VNP15A2H.001',
 'Deleted': False,
 'Description': 'Leaf Area Index (LAI) and Fraction of Photosynthetically '
                'Active Radiation (FPAR)',
 'DocLink': 'https://doi.org/10.5067/viirs/vnp15a2h.001',
 'Platform': 'S-NPP NASA VIIRS',
 'Product': 'VNP15A2H',
 'ProductAndVersion': 'VNP15A2H.001',
 'RasterType': 'Tile',
 'Resolution': '500m',
 'Source': 'LP DAAC',
 'TemporalExtentEnd': 'Present',
 'TemporalExtentStart': '2012-01-19',
 'TemporalGranularity': '8 day',
 'Version': '001'}
{'Available': True,
 'DOI': '10.5067/MODIS/MYD15A2H.006',
 'Deleted': False,
 'Description': 'Leaf Area Index (LAI) and Fraction of Photosynthetically '
                'Active Radiation (FPAR)',
 'DocLink': 'https://doi.org/10.5067/MODIS/MYD15A2H.006',
 'Platform': 'Aqua MODIS',
 'Product': 'MYD15A2H',
 'ProductAndVersion': 'MYD15A2H.006',
 'RasterType': 'Tile',
 'Resolution': '500m',
 'Source': 'LP DAAC',
 'TemporalExtentEnd': 'Present',
 'TemporalExtentStart': '2002-07-04',
 'TemporalGranularity': '8 day',
 'Version': '006'}
{'Available': True,
 'DOI': '10.5067/MODIS/MOD15A2H.061',
 'Deleted': False,
 'Description': 'Leaf Area Index (LAI) and Fraction of Photosynthetically '
                'Active Radiation (FPAR)',
 'DocLink': 'https://doi.org/10.5067/MODIS/MOD15A2H.061',
 'Platform': 'Terra MODIS',
 'Product': 'MOD15A2H',
 'ProductAndVersion': 'MOD15A2H.061',
 'RasterType': 'Tile',
 'Resolution': '500m',
 'Source': 'LP DAAC',
 'TemporalExtentEnd': 'Present',
 'TemporalExtentStart': '2000-02-18',
 'TemporalGranularity': '8 day',
 'Version': '061'}

Using the info above, start a list of desired products by using the highest temporal resolution LAI product, MCD15A3H.006.

prods = ['MCD15A3H.006']     # Start a list for products to be requested, beginning with MCD15A3H.006
prods.append('MOD11A2.061')  # Append the MOD11A2.061 8 day LST product to the list of products desired
prods.append('SRTMGL1_NC.003')  # Append the SRTMGL1_NC.003 product to the list of products desired
prods     

['MCD15A3H.006', 'MOD11A2.061', 'SRTMGL1_NC.003']

2b. Search and Explore Available Layers [List Layers]

The product API allows you to call all of the layers available for a given product. Each product is referenced by its ProductAndVersion property. For a list of the layer names only, print the keys from the dictionary below.

lst_response = r.get('{}product/{}'.format(api, prods[1])).json()  # Request layers for the 2nd product (index 1) in the list: MOD11A2.061
list(lst_response.keys())

['Clear_sky_days',
 'Clear_sky_nights',
 'Day_view_angl',
 'Day_view_time',
 'Emis_31',
 'Emis_32',
 'LST_Day_1km',
 'LST_Night_1km',
 'Night_view_angl',
 'Night_view_time',
 'QC_Day',
 'QC_Night']

Use the dictionary key 'LST_Day_1km' to see the information for that layer in the response.

lst_response['LST_Day_1km'] # Print layer response

{'AddOffset': 0.0,
 'Available': True,
 'DataType': 'float32',
 'Description': 'Day Land Surface Temperature',
 'Dimensions': ['time', 'YDim', 'XDim'],
 'FillValue': 0,
 'IsQA': False,
 'Layer': 'LST_Day_1km',
 'OrigDataType': 'uint16',
 'OrigValidMax': 65535,
 'OrigValidMin': 7500,
 'QualityLayers': "['QC_Day']",
 'QualityProductAndVersion': 'MOD11A2.061',
 'ScaleFactor': 0.02,
 'Units': 'Kelvin',
 'ValidMax': 1310.699951,
 'ValidMin': 150.0,
 'XSize': 1200,
 'YSize': 1200}

AρρEEARS also allows subsetting data spectrally (by band). Create a tupled list with product name and specific layers desired.

layers = [(prods[1],'LST_Day_1km'),(prods[1],'LST_Night_1km')]  # Create tupled list linking desired product with desired layers

Next, request the layers for the MCD15A3H.006 product.

lai_response = r.get('{}product/{}'.format(api, prods[0])).json()  # Request layers for the 1st product (index 0) in the list: MCD15A3H.006
list(lai_response.keys())                                          # Print the LAI layer names

['FparExtra_QC',
 'FparLai_QC',
 'FparStdDev_500m',
 'Fpar_500m',
 'LaiStdDev_500m',
 'Lai_500m']

lai_response['Lai_500m']['Description']  # Make sure the correct layer is requested

'Leaf area index'

Above, Lai_500m is the desired layer within the MCD15A3h.006 product.

Next, append Lai_500m to the tupled list of desired product/layers.

layers.append((prods[0],'Lai_500m')) # Append to tupled list linking desired product with desired layers

Thirdly, request the layers for the SRTMGL1_NC.003 product.

dem_response = r.get('{}product/{}'.format(api, prods[2])).json()  # Request layers for the 3rd product (index 2) in the list: SRTMGL1_NC.003
list(dem_response.keys())                                          # Print the SRTM DEM layer names 

['SRTMGL1_DEM']

Finally, append SRTMGL1_DEM to the tupled list of desired products/layers.

layers.append((prods[2], 'SRTMGL1_DEM')) # Append to tupled list linking desired product with desired layers

Below, take the tupled list (layers) and create a list of dictionaries to store each layer+product combination. This will make it easier to insert into the json file used to submit a request in Section 3.

prodLayer = []
for l in layers:
    prodLayer.append({
            "layer": l[1],
            "product": l[0]
          })
prodLayer

[{'layer': 'LST_Day_1km', 'product': 'MOD11A2.061'},
{'layer': 'LST_Night_1km', 'product': 'MOD11A2.061'},
{'layer': 'Lai_500m', 'product': 'MCD15A3H.006'},
{'layer': 'SRTMGL1_DEM', 'product': 'SRTMGL1_NC.003'}]

3. Submit an Area Request [Tasks]

The Submit task API call provides a way to submit a new request to be processed. It can accept data via JSON, query string, or a combination of both. In the example below, compile a json and submit a request. Tasks in AρρEEARS correspond to each request associated with your user account. Therefore, each of the calls to this service requires an authentication token (see Section 1c.), which is stored in a header below.

token = token_response['token']                      # Save login token to a variable
head = {'Authorization': 'Bearer {}'.format(token)}  # Create a header to store token information, needed to submit a request

3a. Import a Shapefile

In this section, begin by importing a shapefile using the geopandas package. The shapefile is publically available for download from the NPS website.

nps = gpd.read_file('{}nps_boundary.shp'.format(inDir + os.sep)) # Read in shapefile as dataframe using geopandas
print(nps.head())                                                # Print first few lines of dataframe

  UNIT_CODE                                          GIS_Notes  \
0      AMME  LEGACY: contact allen_mccoy@nps.gov for additi...   
1      EBLA  LEGACY: contact allen_mccoy@nps.gov for additi...   
2      LARO  LEGACY: contact allen_mccoy@nps.gov for additi...   
3      LEWI  LEGACY: contact allen_mccoy@nps.gov for additi...   
4      OLYM  LEGACY: contact allen_mccoy@nps.gov for additi...   

                                    UNIT_NAME   DATE_EDIT STATE REGION  \
0                      American Memorial Park  2015-04-22    MP     PW   
1  Ebey's Landing National Historical Reserve  2015-04-22    WA     PW   
2     Lake Roosevelt National Recreation Area  2015-04-22    WA     PW   
3    Lewis and Clark National Historical Park  2015-04-22    WA     PW   
4                       Olympic National Park  2015-04-22    WA     PW   

   GNIS_ID                    UNIT_TYPE CREATED_BY METADATA  \
0  1879026                         Park     Legacy     None   
1  1888910  National Historical Reserve     Legacy     None   
2  1531834     National Recreation Area     Legacy     None   
3  2055170     National Historical Park     Legacy     None   
4  1530459                National Park     Legacy     None   

                 PARKNAME                                           geometry  
0  American Memorial Park  POLYGON ((145.72350 15.22246, 145.72352 15.222...  
1          Ebey's Landing  POLYGON ((-122.65290 48.25379, -122.62396 48.2...  
2          Lake Roosevelt  MULTIPOLYGON (((-118.45200 47.84213, -118.4520...  
3         Lewis and Clark  MULTIPOLYGON (((-124.07495 46.30228, -124.0746...  
4                 Olympic  MULTIPOLYGON (((-124.38061 47.60210, -124.3807...

Below, query the geopandas dataframe for the national park that you are interested in using for your region of interest, here Grand Canyon National Park.

nps_gc = nps[nps['UNIT_NAME']=='Grand Canyon National Park'].to_json() # Extract Grand Canyon NP and set to variable
nps_gc = json.loads(nps_gc)                                            # Convert to json format

3b. Search and Explore Available Projections [Spatial API]

The spatial API provides some helper services used to support submitting area task requests. The call below will retrieve the list of supported projections in AρρEEARS.

projections = r.get('{}spatial/proj'.format(api)).json()  # Call to spatial API, return projs as json
projections                                               # Print projections and information

[{'Name': 'native',
  'Description': 'Native Projection',
  'Platforms': '',
  'Proj4': '',
  'Datum': '',
  'EPSG': '',
  'Units': '',
  'GridMapping': '',
  'Available': True},
 {'Name': 'geographic',
  'Description': 'Geographic',
  'Platforms': "['SRTM', 'ECOSTRESS', 'SSEBop ET', 'GPW', 'ASTER GDEM', 'NASADEM']",
  'Proj4': '+proj=longlat +datum=WGS84 +no_defs',
  'Datum': 'wgs84',
  'EPSG': 4326.0,
  'Units': 'degrees',
  'GridMapping': 'latitude_longitude',
  'Available': True},
 {'Name': 'sinu_modis',
  'Description': 'MODIS Sinusoidal',
  'Platforms': "['Combined MODIS', 'Terra MODIS', 'Aqua MODIS', 'S-NPP NASA VIIRS', 'Global WELD']",
  'Proj4': '+proj=sinu +lon_0=0 +x_0=0 +y_0=0 +R=6371007.181 +units=m +no_defs',
  'Datum': '',
  'EPSG': '',
  'Units': 'meters',
  'GridMapping': 'sinusoidal',
  'Available': True},
 {'Name': 'albers_weld_alaska',
  'Description': 'WELD Albers Equal Area Alaska',
  'Platforms': "['WELD']",
  'Proj4': '+proj=aea +lat_1=55 +lat_2=65 +lat_0=50 +lon_0=-154 +x_0=0 +y_0=0 +datum=WGS84 +units=m +no_defs',
  'Datum': 'wgs84',
  'EPSG': '',
  'Units': 'meters',
  'GridMapping': 'albers_conical_equal_area',
  'Available': True},
 {'Name': 'albers_weld_conus',
  'Description': 'WELD Albers Equal Area CONUS',
  'Platforms': "['WELD']",
  'Proj4': '+proj=aea +lat_1=29.5 +lat_2=45.5 +lat_0=23 +lon_0=-96 +x_0=0 +y_0=0 +datum=WGS84 +units=m +no_defs',
  'Datum': 'wgs84',
  'EPSG': '',
  'Units': 'meters',
  'GridMapping': 'albers_conical_equal_area',
  'Available': True},
 {'Name': 'albers_ard_alaska',
  'Description': 'Landsat ARD Albers Equal Area Alaska',
  'Platforms': "['Landsat ARD']",
  'Proj4': '+proj=aea +lat_1=55 +lat_2=65 +lat_0=50 +lon_0=-154 +x_0=0 +y_0=0 +datum=WGS84 +units=m +no_defs',
  'Datum': 'wgs84',
  'EPSG': '',
  'Units': 'meters',
  'GridMapping': 'albers_conical_equal_area',
  'Available': True},
 {'Name': 'albers_ard_conus',
  'Description': 'Landsat ARD Albers Equal Area CONUS',
  'Platforms': "['Landsat ARD']",
  'Proj4': '+proj=aea +lat_1=29.5 +lat_2=45.5 +lat_0=23 +lon_0=-96 +x_0=0 +y_0=0 +datum=WGS84 +units=m +no_defs',
  'Datum': 'wgs84',
  'EPSG': '',
  'Units': 'meters',
  'GridMapping': 'albers_conical_equal_area',
  'Available': True},
 {'Name': 'albers_ard_hawaii',
  'Description': 'Landsat ARD Albers Equal Area Hawaii',
  'Platforms': "['Landsat ARD']",
  'Proj4': '+proj=aea +lat_1=8 +lat_2=18 +lat_0=3 +lon_0=-157 +x_0=0 +y_0=0 +datum=WGS84 +units=m +no_defs',
  'Datum': 'wgs84',
  'EPSG': '',
  'Units': 'meters',
  'GridMapping': 'albers_conical_equal_area',
  'Available': True},
 {'Name': 'easegrid_2_global',
  'Description': 'EASE-Grid 2.0 Global',
  'Platforms': "['SMAP']",
  'Proj4': '+proj=cea +lon_0=0 +lat_ts=30 +x_0=0 +y_0=0 +datum=WGS84 +units=m +no_defs',
  'Datum': 'wgs84',
  'EPSG': 6933.0,
  'Units': 'meters',
  'GridMapping': 'lambert_cylindrical_equal_area',
  'Available': True},
 {'Name': 'easegrid_2_north',
  'Description': 'EASE-Grid 2.0 Northern Hemisphere',
  'Platforms': "['SMAP']",
  'Proj4': '+proj=laea +lat_0=90 +lon_0=0 +x_0=0 +y_0=0 +datum=WGS84 +units=m +no_defs',
  'Datum': 'wgs84',
  'EPSG': 6931.0,
  'Units': 'meters',
  'GridMapping': 'lambert_cylindrical_equal_area',
  'Available': True},
 {'Name': 'laea_sphere_19',
  'Description': 'Lambert Azimuthal Equal Area Sphere 19',
  'Platforms': "['eMODIS Smoothed NDVI']",
  'Proj4': '+proj=laea +lat_0=45 +lon_0=-100 +x_0=0 +y_0=0 +a=6370997 +b=6370997 +units=m +no_defs',
  'Datum': '',
  'EPSG': '',
  'Units': 'meters',
  'GridMapping': 'lambert_azimuthal_equal_area',
  'Available': True}]

Create a dictionary of projections with projection Name as the keys.

projs = {}                                  # Create an empty dictionary
for p in projections: projs[p['Name']] = p  # Fill dictionary with `Name` as keys
list(projs.keys())                          # Print dictionary keys

['native',
 'geographic',
 'sinu_modis',
 'albers_weld_alaska',
 'albers_weld_conus',
 'albers_ard_alaska',
 'albers_ard_conus',
 'albers_ard_hawaii',
 'easegrid_2_global',
 'easegrid_2_north',
 'laea_sphere_19']

Print the information for the projection used in this tutorial.

projs['geographic']

{'Name': 'geographic',
'Description': 'Geographic',
'Platforms': "['SRTM', 'ECOSTRESS', 'SSEBop ET', 'GPW', 'ASTER GDEM', 'NASADEM']",
'Proj4': '+proj=longlat +datum=WGS84 +no_defs',
'Datum': 'wgs84',
'EPSG': 4326.0,
'Units': 'degrees',
'GridMapping': 'latitude_longitude',
'Available': True}

3c. Compile a JSON [Task Object]

In this section, begin by setting up the information needed to compile an acceptable json for submitting an AρρEEARS area request. For detailed information on required json parameters, see the API Documentation.

task_name = input('Enter a Task Name: ') # User-defined name of the task: 'NPS Vegetation Area' used in example

Enter a Task Name: NPS Vegetation Area

task_type = ['point','area']        # Type of task, area or point
proj = projs['geographic']['Name']  # Set output projection 
outFormat = ['geotiff', 'netcdf4']  # Set output file format type
startDate = '07-01-2017'            # Start of the date range for which to extract data: MM-DD-YYYY
endDate = '07-31-2017'              # End of the date range for which to extract data: MM-DD-YYYY
recurring = False                   # Specify True for a recurring date range
#yearRange = [2000,2016]            # if recurring = True, set yearRange, change start/end date to MM-DD

Below, compile the JSON to be submitted as an area request. Notice that nps_gc is inserted from the shapefile transformed to a json via the geopandas and json packages above in section 3a.

task = {
    'task_type': task_type[1],
    'task_name': task_name,
    'params': {
         'dates': [
         {
             'startDate': startDate,
             'endDate': endDate
         }],
         'layers': prodLayer,
         'output': {
                 'format': {
                         'type': outFormat[0]}, 
                         'projection': proj},
         'geo': nps_gc,
    }
}

3d. Submit a Task Request [Submit Task]

Below, post a call to the API task service, using the task json created above.

task_response = r.post('{}task'.format(api), json=task, headers=head).json()  # Post json to the API task service, return response as json
task_response                                                                 # Print task response

{'task_id': '7a2aa17a-14ed-490a-ad11-9cc019bafad7', 'status': 'pending'}

3e. Retrieve Task Status [Retrieve Task]

This API call will list all of the requests associated with your user account, automatically sorted by date descending with the most recent requests listed first.

The AρρEEARS API contains some helpful formatting resources. Below, limit the API response to 2 entries and set pretty to True to format the response as an organized json, making it easier to read. Additional information on AρρEEARS API pagination and formatting can be found in the API documentation.

params = {'limit': 2, 'pretty': True} # Limit API response to 2 most recent entries, return as pretty json

tasks_response = r.get('{}task'.format(api), params=params, headers=head).json() # Query task service, setting params and header 
tasks_response                                                                   # Print tasks response

[{'params': {'dates': [{'endDate': '07-31-2017', 'startDate': '07-01-2017'}],
   'layers': [{'layer': 'LST_Day_1km', 'product': 'MOD11A2.061'},
    {'layer': 'LST_Night_1km', 'product': 'MOD11A2.061'},
    {'layer': 'Lai_500m', 'product': 'MCD15A3H.006'},
    {'layer': 'SRTMGL1_DEM', 'product': 'SRTMGL1_NC.003'}],
   'output': {'format': {'type': 'geotiff'}, 'projection': 'geographic'}},
  'status': 'pending',
  'created': '2022-05-04T19:33:52.325868',
  'task_id': 'e6151799-8ee9-46da-af8c-f47c2cc2bd8b',
  'updated': '2022-05-04T19:33:56.532071',
  'user_id': 'user@email.com',
  'estimate': {'request_size': 196969757.51610893},
  'has_swath': False,
  'task_name': 'NPS Vegetation Area',
  'task_type': 'area',
  'api_version': 'v1',
  'svc_version': '3.2.1',
  'web_version': None,
  'has_nsidc_daac': False,
  'expires_on': '2022-06-03T19:33:56.532071'},
 {'error': None,
  'params': {'dates': [{'endDate': '12-31-2017',
     'startDate': '01-01-2016',
     'yearRange': [1980, 2050]}],
   'layers': [{'layer': 'LST_Day_1km', 'product': 'MOD11A2.061'},
    {'layer': 'LST_Night_1km', 'product': 'MOD11A2.061'},
    {'layer': '_1_km_16_days_EVI', 'product': 'MOD13A2.061'},
    {'layer': '_1_km_16_days_NDVI', 'product': 'MOD13A2.061'}]},
  'status': 'done',
  'created': '2022-04-28T15:53:41.181032',
  'task_id': '6856620f-1ca3-48b5-8d30-b6ffd8b6c9b4',
  'updated': '2022-04-28T15:57:16.995633',
  'user_id': 'user@email.com',
  'attempts': 1,
  'estimate': {'request_size': 408},
  'retry_at': None,
  'completed': '2022-04-28T15:57:16.994581',
  'has_swath': False,
  'task_name': 'Point Demo',
  'task_type': 'point',
  'api_version': None,
  'svc_version': '3.2.1',
  'web_version': '3.2.1',
  'size_category': '0',
  'has_nsidc_daac': False,
  'expires_on': '2022-05-28T15:57:16.995633'}]

Next, take the task id returned from the task_response that was generated when submitting your request, and use the AρρEEARS API status service to check the status of your request.

task_id = task_response['task_id']                                               # Set task id from request submission
status_response = r.get('{}status/{}'.format(api, task_id), headers=head).json() # Call status service with specific task ID & user credentials
status_response                                                        

{'task_id': '7a2aa17a-14ed-490a-ad11-9cc019bafad7',
'status': 'pending',
'user_id': 'user@email.com',
'updated': '2022-05-04T19:33:56.532071',
'status_type': 'task'}

Above, if your request is still processing, you can find information on the status of how close it is to completing.

Below, call the task service for your request every 20 seconds to check the status of your request.

# Ping API until request is complete, then continue to Section 4
starttime = time.time()
while r.get('{}task/{}'.format(api, task_id), headers=head).json()['status'] != 'done':
    print(r.get('{}task/{}'.format(api, task_id), headers=head).json()['status'])
    time.sleep(20.0 - ((time.time() - starttime) % 20.0))
print(r.get('{}task/{}'.format(api, task_id), headers=head).json()['status'])

pending
pending
pending
pending
pending
pending
pending
pending
pending
processing
processing
processing
done

4. Download a Request [Bundle API]

Before downloading the request output, set up an output directory to store the output files, and examine the files contained in the request output.

destDir = os.path.join(inDir, task_name)                # Set up output directory using input directory and task name
if not os.path.exists(destDir):os.makedirs(destDir)     # Create the output directory

4a. Explore Files in Request Output [List Files]

The bundle API provides information about completed tasks. For any completed task, a bundle can be queried to return the files contained as a part of the task request. Below, call the bundle API and return all of the output files.

bundle = r.get('{}bundle/{}'.format(api,task_id), headers=head).json()  # Call API and return bundle contents for the task_id as json
bundle                                                    # Print bundle contents

    {'files': [{'sha256': '9931687ff1bda429c6fe1b3bfaf67ea60ca82b118dd542c5447a271e933ac19e',
   'file_id': '6cccc42c-0b57-4e7b-9234-1b82d68dcf1f',
   'file_name': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_Lai_500m_doy2017181_aid0001.tif',
   'file_size': 13516,
   'file_type': 'tif'},
  {'sha256': '184b3039d86523ea38a6df08a862dfa717694c03bca2c1e9526ae80dad9d2d77',
   'file_id': 'c6ae31d3-3307-44d4-951f-841ac6ab9256',
   'file_name': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_Lai_500m_doy2017185_aid0001.tif',
   'file_size': 13435,
   'file_type': 'tif'},
  {'sha256': '1e9e90105902a6a20fec619816ac85ef05b74e28c616f0be68f70d49baac4627',
   'file_id': '408d8de6-9a4c-4db9-826b-7ffc791615a4',
   'file_name': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_Lai_500m_doy2017189_aid0001.tif',
   'file_size': 13713,
   'file_type': 'tif'},
  {'sha256': '0893f432bb8985e945993835d2e5d034a49216d298084c9b5be877280856457a',
   'file_id': 'cf5e92ab-200f-4cf9-9adc-199526ea83e7',
   'file_name': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_Lai_500m_doy2017193_aid0001.tif',
   'file_size': 13939,
   'file_type': 'tif'},
  {'sha256': '5df866a22274cbac94ffbdfa6d8005c84993e775d02e9dcd48b4b538b58d021c',
   'file_id': '7ee309e4-54e5-40aa-b672-517251c62821',
   'file_name': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_Lai_500m_doy2017197_aid0001.tif',
   'file_size': 14176,
   'file_type': 'tif'},
  {'sha256': '9a452782fe59e3271e161d7cd0377aa3e7872206cfff72fa1452e5447c80007b',
   'file_id': 'fa0ba79f-ca5a-4dbb-a7cf-09fb77157ddf',
   'file_name': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_Lai_500m_doy2017201_aid0001.tif',
   'file_size': 14333,
   'file_type': 'tif'},
  {'sha256': 'a562c68fdcbd86a559b59485debbe3f6d9ff56be2b31460e38c560f1f05d2df2',
   'file_id': '3687d49e-82cb-4a92-b053-1d32cf7d2e92',
   'file_name': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_Lai_500m_doy2017205_aid0001.tif',
   'file_size': 13401,
   'file_type': 'tif'},
  {'sha256': 'ad1fede1795360af0a56adb0c445889baa53f63d1329efe18ead724357a2faa8',
   'file_id': 'c9afe924-0d70-44b8-b17a-22d3e9c9131e',
   'file_name': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_Lai_500m_doy2017209_aid0001.tif',
   'file_size': 13580,
   'file_type': 'tif'},
  {'sha256': '4b3db3b622e0fe10afd0be0d61b479cc41741f8c1f6dd6b00f9a5d66728aa6e1',
   'file_id': 'd2d2728f-2258-4312-93c3-567832e3659e',
   'file_name': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparLai_QC_doy2017181_aid0001.tif',
   'file_size': 8968,
   'file_type': 'tif'},
  {'sha256': '123e69417f49ebc75f2d0641359148f629fb02c6f50f18bb80b4d1cdc11c7d2b',
   'file_id': '6d4461e5-b55e-4552-821a-6707eee179c8',
   'file_name': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparLai_QC_doy2017185_aid0001.tif',
   'file_size': 9435,
   'file_type': 'tif'},
  {'sha256': '16cf670e237efeb85337c4b19888308f9a135ae8bd75f49cc844ec38b7b81802',
   'file_id': '8d5a92a6-9c55-4d2f-a45d-e51753f174d4',
   'file_name': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparLai_QC_doy2017189_aid0001.tif',
   'file_size': 9541,
   'file_type': 'tif'},
  {'sha256': 'ce243dec74c6347a659150c8d49cd9f9ff9d768e60a41657b87559f2406a9b59',
   'file_id': '29f52ef0-7e54-48f8-b8dd-4d47e81ed0a1',
   'file_name': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparLai_QC_doy2017193_aid0001.tif',
   'file_size': 9989,
   'file_type': 'tif'},
  {'sha256': '2d4fb4d1a428b304d8cf814ed409cf48e1cb8027293194246e4aff49436f4238',
   'file_id': '55f39f6a-fe6a-4652-95ce-91f9b4127574',
   'file_name': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparLai_QC_doy2017197_aid0001.tif',
   'file_size': 8702,
   'file_type': 'tif'},
  {'sha256': 'e02b37b867fdddefdee22b0b59971082573df9652db3b07483034ca4591e29c8',
   'file_id': '67a68a12-c875-424b-be97-2d529acd4cd5',
   'file_name': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparLai_QC_doy2017201_aid0001.tif',
   'file_size': 10746,
   'file_type': 'tif'},
  {'sha256': '1f436194cb0e80d179fbcf0f5a59e7ebcb6e76d5fb0f51d3a29372fb3cfc1248',
   'file_id': 'f6beb41a-3029-40f3-9920-fbef601d3176',
   'file_name': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparLai_QC_doy2017205_aid0001.tif',
   'file_size': 10347,
   'file_type': 'tif'},
  {'sha256': 'adf5d2e01a3392ab46226af2fb792a002b370d3af7f08e46334391fe5a12a773',
   'file_id': '45d9c213-fd9c-42bc-b65e-fe371e09041e',
   'file_name': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparLai_QC_doy2017209_aid0001.tif',
   'file_size': 11683,
   'file_type': 'tif'},
  {'sha256': 'a30f111e5f0a7e4ec956692cff4f574bfaf48b2931ea86cbf91e500f3597fb5b',
   'file_id': '48b0c284-4d1a-4603-8b00-2b969eb31975',
   'file_name': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparExtra_QC_doy2017181_aid0001.tif',
   'file_size': 9143,
   'file_type': 'tif'},
  {'sha256': 'a2a3c3c9f93fa4b7be2aa3d334bb0505f76c168d325d66c11f143be02fa17b0f',
   'file_id': 'abee5d9a-4dd4-473f-bfb4-e7f8945dee99',
   'file_name': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparExtra_QC_doy2017185_aid0001.tif',
   'file_size': 10524,
   'file_type': 'tif'},
  {'sha256': '46b22cbcdd92bc739292269153d2d69157c1fd735fa9dd8e5b067cd59eed179f',
   'file_id': '8794e5c1-d484-41be-82c6-8fe3d41e1685',
   'file_name': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparExtra_QC_doy2017189_aid0001.tif',
   'file_size': 10496,
   'file_type': 'tif'},
  {'sha256': '0eac59856b0b4be230d7c0301ff12f81ae3d918f62504232e9640f1b13130aa0',
   'file_id': 'db011c83-4430-4517-b955-abb6abdbda16',
   'file_name': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparExtra_QC_doy2017193_aid0001.tif',
   'file_size': 11362,
   'file_type': 'tif'},
  {'sha256': '219f2dbbb2b073422676d6e44c845eb40131fe1ad9ab4d55c38a5219efa44f25',
   'file_id': '15d61907-f413-4fee-b54f-697c5f648e4c',
   'file_name': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparExtra_QC_doy2017197_aid0001.tif',
   'file_size': 11271,
   'file_type': 'tif'},
  {'sha256': 'b34eead90d7fdc9df4a025de61c7c37f9208c92614c6919849bdbd1b77c246d0',
   'file_id': '9c942ec0-901e-47af-8272-e58f0e221ca1',
   'file_name': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparExtra_QC_doy2017201_aid0001.tif',
   'file_size': 12161,
   'file_type': 'tif'},
  {'sha256': '2f6d5348f412aa7ffe93e820c1e4ad75cf727c3259c6d212d5e599c7192643e4',
   'file_id': 'a8640cdd-f062-4413-8381-5f678d628d97',
   'file_name': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparExtra_QC_doy2017205_aid0001.tif',
   'file_size': 11749,
   'file_type': 'tif'},
  {'sha256': '94c7ceaaab9505dd4b641a0835b1b75661b84e7e7c0175a2f67f132e8181f24d',
   'file_id': 'c683dd54-bc64-4066-83db-a0f41aff82fd',
   'file_name': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparExtra_QC_doy2017209_aid0001.tif',
   'file_size': 12708,
   'file_type': 'tif'},
  {'sha256': '81ef57707a7dd79c7ad428f34937d73e389545e27142efc43c900248f1909dc0',
   'file_id': '47582260-fc40-44dd-b6ca-5554aebe96d1',
   'file_name': 'MOD11A2.061_2017175_to_2017212/MOD11A2.061_LST_Day_1km_doy2017177_aid0001.tif',
   'file_size': 16173,
   'file_type': 'tif'},
  {'sha256': '28bec1a4491e9203bc134740d3d0679fe84bef9f4e332cb8d2919cc0f7035ce8',
   'file_id': '27e60c69-e9f2-46d8-a612-bd84c5d128b0',
   'file_name': 'MOD11A2.061_2017175_to_2017212/MOD11A2.061_LST_Day_1km_doy2017185_aid0001.tif',
   'file_size': 16240,
   'file_type': 'tif'},
  {'sha256': '915dae800f01121471586af401052846f3c993baec54d713bce2023ec9eb3b2a',
   'file_id': '3b9b2e3c-6f4f-4792-9766-5a27828fd80a',
   'file_name': 'MOD11A2.061_2017175_to_2017212/MOD11A2.061_LST_Day_1km_doy2017193_aid0001.tif',
   'file_size': 16492,
   'file_type': 'tif'},
  {'sha256': '90960a1c3d150c5b4d0281383ec7a2ab27b5c823acfa631750607e1516a65c96',
   'file_id': '7b437337-74b1-4647-94a1-318cb864d9de',
   'file_name': 'MOD11A2.061_2017175_to_2017212/MOD11A2.061_LST_Day_1km_doy2017201_aid0001.tif',
   'file_size': 16766,
   'file_type': 'tif'},
  {'sha256': 'f87ab5004054a2a6fc7d56b9020cc94cffd01c4ae925920b3fc57764dc654e16',
   'file_id': '5c681696-e520-4370-8e5c-406d7a9aff72',
   'file_name': 'MOD11A2.061_2017175_to_2017212/MOD11A2.061_LST_Day_1km_doy2017209_aid0001.tif',
   'file_size': 16847,
   'file_type': 'tif'},
  {'sha256': '40553b5bf520407c8646d97e89c2d29f90dbfd115ca1cc3dff8c5dc8d516e921',
   'file_id': '93c89b94-3b8c-4f75-b91d-d36334048aad',
   'file_name': 'MOD11A2.061_2017175_to_2017212/MOD11A2.061_LST_Night_1km_doy2017177_aid0001.tif',
   'file_size': 16582,
   'file_type': 'tif'},
  {'sha256': 'bc7f485b4abf0dc0b1bdeb04f6325e1db3919f1ea0818421a511b8539152340c',
   'file_id': '395170fd-72bc-46cb-804f-276f3439f635',
   'file_name': 'MOD11A2.061_2017175_to_2017212/MOD11A2.061_LST_Night_1km_doy2017185_aid0001.tif',
   'file_size': 16634,
   'file_type': 'tif'},
  {'sha256': 'ce3b4b55b2d584db2d58ffe7f9c8968edcb36354b9348da4efed44587a542f1f',
   'file_id': 'b8a3c0cc-18bc-49d0-8016-6ccdeeafd7ae',
   'file_name': 'MOD11A2.061_2017175_to_2017212/MOD11A2.061_LST_Night_1km_doy2017193_aid0001.tif',
   'file_size': 16546,
   'file_type': 'tif'},
  {'sha256': 'c5810df67f19e20d3b1ed10b7e1144b2c02775c19384c148ee3a4a6a296f0bee',
   'file_id': '8c6f6072-664a-482f-8cb8-730b855e1067',
   'file_name': 'MOD11A2.061_2017175_to_2017212/MOD11A2.061_LST_Night_1km_doy2017201_aid0001.tif',
   'file_size': 16315,
   'file_type': 'tif'},
  {'sha256': '2131d4df93f3a67f1aa43fe3a479b28e5363ca6a83fae55eaee9dd29183d4c6f',
   'file_id': '9d59b017-5f97-4db2-ac43-3801105264fa',
   'file_name': 'MOD11A2.061_2017175_to_2017212/MOD11A2.061_LST_Night_1km_doy2017209_aid0001.tif',
   'file_size': 16469,
   'file_type': 'tif'},
  {'sha256': '8ea26c647b3f0f40a5da1835ab369730cbfc4795ee9274fbb3daffdf569e6811',
   'file_id': '3655abb2-42b7-41dd-b4c7-075cd06a3af6',
   'file_name': 'MOD11A2.061_2017175_to_2017212/MOD11A2.061_QC_Day_doy2017177_aid0001.tif',
   'file_size': 2683,
   'file_type': 'tif'},
  {'sha256': '1d93ac0487374af9c677a7e1cc0b2859c8d262f1157b430baa404fdac0ab2a9b',
   'file_id': 'c97daf58-2c9a-4b36-83c7-bc8cae3fa875',
   'file_name': 'MOD11A2.061_2017175_to_2017212/MOD11A2.061_QC_Day_doy2017185_aid0001.tif',
   'file_size': 2877,
   'file_type': 'tif'},
  {'sha256': '4a944c7800298d1c5cc3cc245113dcb31bcc7d822d77005a7ab8ae2c1302e2b2',
   'file_id': '7cda6965-0276-4939-afe2-d16bfbd99ff3',
   'file_name': 'MOD11A2.061_2017175_to_2017212/MOD11A2.061_QC_Day_doy2017193_aid0001.tif',
   'file_size': 2531,
   'file_type': 'tif'},
  {'sha256': 'a9c59e8a6409a3cfbdd25ae00efbd706a0521a3e1f274d34356c6dba74a3c301',
   'file_id': '38d3913a-c349-4add-bcb1-62d374bf805d',
   'file_name': 'MOD11A2.061_2017175_to_2017212/MOD11A2.061_QC_Day_doy2017201_aid0001.tif',
   'file_size': 2910,
   'file_type': 'tif'},
  {'sha256': '1f6bc07f5d6cd6b054438a651d52483599d3b061abe8143e02dbeb43184e7560',
   'file_id': '2cb5f949-9403-46e1-8832-b8471703bf2e',
   'file_name': 'MOD11A2.061_2017175_to_2017212/MOD11A2.061_QC_Day_doy2017209_aid0001.tif',
   'file_size': 2994,
   'file_type': 'tif'},
  {'sha256': '1455174185f312a01a56addfd1eed3983c10241311e7477653b6c49d2caf10c1',
   'file_id': 'ba376026-d693-45a6-96b6-8caaa057424c',
   'file_name': 'MOD11A2.061_2017175_to_2017212/MOD11A2.061_QC_Night_doy2017177_aid0001.tif',
   'file_size': 2192,
   'file_type': 'tif'},
  {'sha256': '2eac507deb32b3926976050b20302bb4521bd9ef89c4ed5efd3888688d80d84d',
   'file_id': 'd5d7cb58-9958-42d5-9e09-c1a4dd4ca3f8',
   'file_name': 'MOD11A2.061_2017175_to_2017212/MOD11A2.061_QC_Night_doy2017185_aid0001.tif',
   'file_size': 2278,
   'file_type': 'tif'},
  {'sha256': 'ce7ea4f3be7cf248565492735487c49436c18abd208c27930fd707cc36777d16',
   'file_id': '2a283c2f-8370-463a-8695-eb1ddbe86ae9',
   'file_name': 'MOD11A2.061_2017175_to_2017212/MOD11A2.061_QC_Night_doy2017193_aid0001.tif',
   'file_size': 2718,
   'file_type': 'tif'},
  {'sha256': 'fb82fd47e349b966572f777a5d96e1a0b57cd87802ccfd0bf97ebfadde19b397',
   'file_id': '46a70d5e-bf57-4313-9fd3-3a73ddfa7c37',
   'file_name': 'MOD11A2.061_2017175_to_2017212/MOD11A2.061_QC_Night_doy2017201_aid0001.tif',
   'file_size': 2730,
   'file_type': 'tif'},
  {'sha256': 'c833c74e708df50a1630468927c50010d5cf013a90c3448176c9e73ac29e617a',
   'file_id': 'f71f158d-d2a8-4191-a0c9-c891a1958584',
   'file_name': 'MOD11A2.061_2017175_to_2017212/MOD11A2.061_QC_Night_doy2017209_aid0001.tif',
   'file_size': 2860,
   'file_type': 'tif'},
  {'sha256': '54182330abc58274d8cfcf7523b6de82640e9058fd8412b50f6ea9740817c458',
   'file_id': '3d753c3c-0ab1-47f4-bf01-b02195cdbc80',
   'file_name': 'SRTMGL1_NC.003_2000001_to_2022084/SRTMGL1_NC.003_SRTMGL1_DEM_doy2000042_aid0001.tif',
   'file_size': 14021599,
   'file_type': 'tif'},
  {'sha256': 'b422238b676705a85cd490c8a1f20fec505ab0b1405561f33fb5ffdbeefb74a1',
   'file_id': '69fcec5b-d8ad-49a8-baa7-081c2475c902',
   'file_name': 'SRTMGL1_NUMNC.003_2000001_to_2022084/SRTMGL1_NUMNC.003_SRTMGL1_NUM_doy2000042_aid0001.tif',
   'file_size': 2255718,
   'file_type': 'tif'},
  {'sha256': 'e62f9a6a8284ac1be7a2d1e07aa139727d90fa79149446abba6465c825dbf85e',
   'file_id': 'ccf3efe4-86ab-453b-ad7f-f073bb2dfb8b',
   'file_name': 'MCD15A3H-006-FparLai-QC-lookup.csv',
   'file_size': 3939,
   'file_type': 'csv'},
  {'sha256': '88e341b6839e1d85a41b615ef9c380f58f9883d91109ef192fce8690feb6673b',
   'file_id': 'b6575b89-c2b9-46fb-8247-216c41548458',
   'file_name': 'MCD15A3H-006-FparExtra-QC-lookup.csv',
   'file_size': 4737,
   'file_type': 'csv'},
  {'sha256': 'f5ad5254fb2cd4e1c751bba66cb13d1ffa6bb699d9f24aa631caea95d844d8c6',
   'file_id': '7432158c-029d-45a3-8315-d8a401eb772c',
   'file_name': 'MOD11A2-061-QC-Day-lookup.csv',
   'file_size': 516,
   'file_type': 'csv'},
  {'sha256': '84265a384dcc629d7e4d37b1b92c784c396bfdd8211d2b030b21840621dbf211',
   'file_id': '3bd85348-07c1-4e10-802d-9f9a284b5f88',
   'file_name': 'MOD11A2-061-QC-Night-lookup.csv',
   'file_size': 631,
   'file_type': 'csv'},
  {'sha256': 'e712cb891b6844c15eeda5cad9912c60fc6fd6426a229356622ad11be2ab4f0f',
   'file_id': '5d42d6c6-4bc3-4b8f-9d45-f7f93398b20d',
   'file_name': 'SRTMGL1-NUMNC-003-SRTMGL1-NUM-lookup.csv',
   'file_size': 1542,
   'file_type': 'csv'},
  {'sha256': '734997dd32286465f2fea45f2100559f262d08fcef9ff749eefe75204a154c00',
   'file_id': '17c44fc8-b8dc-408a-a51e-50e37cc27425',
   'file_name': 'MCD15A3H-006-FparLai-QC-Statistics-QA.csv',
   'file_size': 912,
   'file_type': 'csv'},
  {'sha256': '4b6b3e57f5d9aa13d643f6bdc878f6f830e1cb7a901cad0571ec5a63102bb3e7',
   'file_id': 'abc5db6f-5a2c-4650-aec1-ae19ad167ea0',
   'file_name': 'MCD15A3H-006-FparExtra-QC-Statistics-QA.csv',
   'file_size': 1093,
   'file_type': 'csv'},
  {'sha256': '9dc9387dfa6720371af713940f3839d1f0160e924f05b0d38f9fbc60b70fdbc8',
   'file_id': '60e2faf9-3283-44fc-985b-a2285e1f8c16',
   'file_name': 'MOD11A2-061-QC-Day-Statistics-QA.csv',
   'file_size': 306,
   'file_type': 'csv'},
  {'sha256': '95df1cabed8e3937a4af2750899cc6fbda28ec47bc3d5cbb702b17dcb9cdedf7',
   'file_id': '3d5af245-0844-4abc-a522-97f3d6ff2828',
   'file_name': 'MOD11A2-061-QC-Night-Statistics-QA.csv',
   'file_size': 326,
   'file_type': 'csv'},
  {'sha256': 'd00db348f325f3b96bf2c216aac89064f3d4789c68016ccb7b53afe8215dbd8e',
   'file_id': '3a4265d2-0f0c-4e83-ba35-b7b5743aede2',
   'file_name': 'SRTMGL1-NUMNC-003-SRTMGL1-NUM-Statistics-QA.csv',
   'file_size': 552,
   'file_type': 'csv'},
  {'sha256': '0f6d1ae3d9707b59159f7826a7b77a5b22c3d24cd30974083de8e220c82c5440',
   'file_id': 'e336ec32-d2c2-4c41-b96c-135db49f3342',
   'file_name': 'MCD15A3H-006-Statistics.csv',
   'file_size': 1327,
   'file_type': 'csv'},
  {'sha256': 'd6fe8727b6e9714683c3316b4570c768b91c6ba2493689bbdf91ee8707c0f205',
   'file_id': 'f0334a15-20cf-413e-89c0-1f039c60762a',
   'file_name': 'MOD11A2-061-Statistics.csv',
   'file_size': 1957,
   'file_type': 'csv'},
  {'sha256': '2eac4d929df3ec54f8a400b032d876aed7211726a2cb4c5ac6e80bfc3d5cc31e',
   'file_id': '917619e6-5890-484f-8e58-8238660cb503',
   'file_name': 'SRTMGL1-NC-003-Statistics.csv',
   'file_size': 344,
   'file_type': 'csv'},
  {'sha256': '64b6630f52de2e8c46b4e9efe4770580de8d5fd7235dffc098968febf010b2c5',
   'file_id': '986f4160-a696-4fb5-832a-9984a986f9d0',
   'file_name': 'NPS-Vegetation-Area-granule-list.txt',
   'file_size': 4514,
   'file_type': 'txt'},
  {'sha256': 'f94ef498ab64f09b76d3fe958490a398469dc3627e3b9c34aa3e7d0ce1703904',
   'file_id': '4ba2c9f2-bb98-496f-94c0-f27aba97e0e5',
   'file_name': 'NPS-Vegetation-Area-request.json',
   'file_size': 13614112,
   'file_type': 'json'},
  {'sha256': 'f3d44060fb40898dd37ead368be75616bbd2601e552d90710b9afea419f602c6',
   'file_id': 'b3df0fcc-c628-4815-82d7-d53218a46610',
   'file_name': 'NPS-Vegetation-Area-MCD15A3H-006-metadata.xml',
   'file_size': 22173,
   'file_type': 'xml'},
  {'sha256': 'd80167f45a1f965a7c7c90334bfc2427b3a2abe2e64558eda2bb5bc872516fe1',
   'file_id': 'd46129c7-711a-4112-a1b7-6eb031c6380f',
   'file_name': 'NPS-Vegetation-Area-MOD11A2-061-metadata.xml',
   'file_size': 22129,
   'file_type': 'xml'},
  {'sha256': 'fb874b30cc59225190a42bcd0b4dee7cbef6f5d3d354a7143e3bd776b0204778',
   'file_id': 'c2fac1f5-38ed-44fb-b083-7471dc5c97b2',
   'file_name': 'NPS-Vegetation-Area-SRTMGL1-NC-003-metadata.xml',
   'file_size': 22095,
   'file_type': 'xml'},
  {'sha256': 'a1b58ae7bfd5f41317c05af537cec322891eaba73a5edb64a5728fc3f7252a1a',
   'file_id': '49407a8c-892c-4e14-b03d-d4570083335f',
   'file_name': 'README.md',
   'file_size': 24574,
   'file_type': 'txt'}],
 'created': '2022-03-25T15:13:43.689619',
 'task_id': '7a2aa17a-14ed-490a-ad11-9cc019bafad7',
 'updated': '2022-03-25T15:18:07.422441',
 'bundle_type': 'area'}

4b. Download Files in a Request (Automation) [Download File]

Now, use the contents of the bundle to select the file name and id and store as a dictionary.

files = {}                                                       # Create empty dictionary
for f in bundle['files']: files[f['file_id']] = f['file_name']   # Fill dictionary with file_id as keys and file_name as values
files    

{'6cccc42c-0b57-4e7b-9234-1b82d68dcf1f': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_Lai_500m_doy2017181_aid0001.tif',
 'c6ae31d3-3307-44d4-951f-841ac6ab9256': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_Lai_500m_doy2017185_aid0001.tif',
 '408d8de6-9a4c-4db9-826b-7ffc791615a4': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_Lai_500m_doy2017189_aid0001.tif',
 'cf5e92ab-200f-4cf9-9adc-199526ea83e7': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_Lai_500m_doy2017193_aid0001.tif',
 '7ee309e4-54e5-40aa-b672-517251c62821': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_Lai_500m_doy2017197_aid0001.tif',
 'fa0ba79f-ca5a-4dbb-a7cf-09fb77157ddf': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_Lai_500m_doy2017201_aid0001.tif',
 '3687d49e-82cb-4a92-b053-1d32cf7d2e92': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_Lai_500m_doy2017205_aid0001.tif',
 'c9afe924-0d70-44b8-b17a-22d3e9c9131e': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_Lai_500m_doy2017209_aid0001.tif',
 'd2d2728f-2258-4312-93c3-567832e3659e': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparLai_QC_doy2017181_aid0001.tif',
 '6d4461e5-b55e-4552-821a-6707eee179c8': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparLai_QC_doy2017185_aid0001.tif',
 '8d5a92a6-9c55-4d2f-a45d-e51753f174d4': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparLai_QC_doy2017189_aid0001.tif',
 '29f52ef0-7e54-48f8-b8dd-4d47e81ed0a1': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparLai_QC_doy2017193_aid0001.tif',
 '55f39f6a-fe6a-4652-95ce-91f9b4127574': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparLai_QC_doy2017197_aid0001.tif',
 '67a68a12-c875-424b-be97-2d529acd4cd5': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparLai_QC_doy2017201_aid0001.tif',
 'f6beb41a-3029-40f3-9920-fbef601d3176': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparLai_QC_doy2017205_aid0001.tif',
 '45d9c213-fd9c-42bc-b65e-fe371e09041e': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparLai_QC_doy2017209_aid0001.tif',
 '48b0c284-4d1a-4603-8b00-2b969eb31975': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparExtra_QC_doy2017181_aid0001.tif',
 'abee5d9a-4dd4-473f-bfb4-e7f8945dee99': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparExtra_QC_doy2017185_aid0001.tif',
 '8794e5c1-d484-41be-82c6-8fe3d41e1685': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparExtra_QC_doy2017189_aid0001.tif',
 'db011c83-4430-4517-b955-abb6abdbda16': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparExtra_QC_doy2017193_aid0001.tif',
 '15d61907-f413-4fee-b54f-697c5f648e4c': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparExtra_QC_doy2017197_aid0001.tif',
 '9c942ec0-901e-47af-8272-e58f0e221ca1': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparExtra_QC_doy2017201_aid0001.tif',
 'a8640cdd-f062-4413-8381-5f678d628d97': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparExtra_QC_doy2017205_aid0001.tif',
 'c683dd54-bc64-4066-83db-a0f41aff82fd': 'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparExtra_QC_doy2017209_aid0001.tif',
 '47582260-fc40-44dd-b6ca-5554aebe96d1': 'MOD11A2.061_2017175_to_2017212/MOD11A2.061_LST_Day_1km_doy2017177_aid0001.tif',
 '27e60c69-e9f2-46d8-a612-bd84c5d128b0': 'MOD11A2.061_2017175_to_2017212/MOD11A2.061_LST_Day_1km_doy2017185_aid0001.tif',
 '3b9b2e3c-6f4f-4792-9766-5a27828fd80a': 'MOD11A2.061_2017175_to_2017212/MOD11A2.061_LST_Day_1km_doy2017193_aid0001.tif',
 '7b437337-74b1-4647-94a1-318cb864d9de': 'MOD11A2.061_2017175_to_2017212/MOD11A2.061_LST_Day_1km_doy2017201_aid0001.tif',
 '5c681696-e520-4370-8e5c-406d7a9aff72': 'MOD11A2.061_2017175_to_2017212/MOD11A2.061_LST_Day_1km_doy2017209_aid0001.tif',
 '93c89b94-3b8c-4f75-b91d-d36334048aad': 'MOD11A2.061_2017175_to_2017212/MOD11A2.061_LST_Night_1km_doy2017177_aid0001.tif',
 '395170fd-72bc-46cb-804f-276f3439f635': 'MOD11A2.061_2017175_to_2017212/MOD11A2.061_LST_Night_1km_doy2017185_aid0001.tif',
 'b8a3c0cc-18bc-49d0-8016-6ccdeeafd7ae': 'MOD11A2.061_2017175_to_2017212/MOD11A2.061_LST_Night_1km_doy2017193_aid0001.tif',
 '8c6f6072-664a-482f-8cb8-730b855e1067': 'MOD11A2.061_2017175_to_2017212/MOD11A2.061_LST_Night_1km_doy2017201_aid0001.tif',
 '9d59b017-5f97-4db2-ac43-3801105264fa': 'MOD11A2.061_2017175_to_2017212/MOD11A2.061_LST_Night_1km_doy2017209_aid0001.tif',
 '3655abb2-42b7-41dd-b4c7-075cd06a3af6': 'MOD11A2.061_2017175_to_2017212/MOD11A2.061_QC_Day_doy2017177_aid0001.tif',
 'c97daf58-2c9a-4b36-83c7-bc8cae3fa875': 'MOD11A2.061_2017175_to_2017212/MOD11A2.061_QC_Day_doy2017185_aid0001.tif',
 '7cda6965-0276-4939-afe2-d16bfbd99ff3': 'MOD11A2.061_2017175_to_2017212/MOD11A2.061_QC_Day_doy2017193_aid0001.tif',
 '38d3913a-c349-4add-bcb1-62d374bf805d': 'MOD11A2.061_2017175_to_2017212/MOD11A2.061_QC_Day_doy2017201_aid0001.tif',
 '2cb5f949-9403-46e1-8832-b8471703bf2e': 'MOD11A2.061_2017175_to_2017212/MOD11A2.061_QC_Day_doy2017209_aid0001.tif',
 'ba376026-d693-45a6-96b6-8caaa057424c': 'MOD11A2.061_2017175_to_2017212/MOD11A2.061_QC_Night_doy2017177_aid0001.tif',
 'd5d7cb58-9958-42d5-9e09-c1a4dd4ca3f8': 'MOD11A2.061_2017175_to_2017212/MOD11A2.061_QC_Night_doy2017185_aid0001.tif',
 '2a283c2f-8370-463a-8695-eb1ddbe86ae9': 'MOD11A2.061_2017175_to_2017212/MOD11A2.061_QC_Night_doy2017193_aid0001.tif',
 '46a70d5e-bf57-4313-9fd3-3a73ddfa7c37': 'MOD11A2.061_2017175_to_2017212/MOD11A2.061_QC_Night_doy2017201_aid0001.tif',
 'f71f158d-d2a8-4191-a0c9-c891a1958584': 'MOD11A2.061_2017175_to_2017212/MOD11A2.061_QC_Night_doy2017209_aid0001.tif',
 '3d753c3c-0ab1-47f4-bf01-b02195cdbc80': 'SRTMGL1_NC.003_2000001_to_2022084/SRTMGL1_NC.003_SRTMGL1_DEM_doy2000042_aid0001.tif',
 '69fcec5b-d8ad-49a8-baa7-081c2475c902': 'SRTMGL1_NUMNC.003_2000001_to_2022084/SRTMGL1_NUMNC.003_SRTMGL1_NUM_doy2000042_aid0001.tif',
 'ccf3efe4-86ab-453b-ad7f-f073bb2dfb8b': 'MCD15A3H-006-FparLai-QC-lookup.csv',
 'b6575b89-c2b9-46fb-8247-216c41548458': 'MCD15A3H-006-FparExtra-QC-lookup.csv',
 '7432158c-029d-45a3-8315-d8a401eb772c': 'MOD11A2-061-QC-Day-lookup.csv',
 '3bd85348-07c1-4e10-802d-9f9a284b5f88': 'MOD11A2-061-QC-Night-lookup.csv',
 '5d42d6c6-4bc3-4b8f-9d45-f7f93398b20d': 'SRTMGL1-NUMNC-003-SRTMGL1-NUM-lookup.csv',
 '17c44fc8-b8dc-408a-a51e-50e37cc27425': 'MCD15A3H-006-FparLai-QC-Statistics-QA.csv',
 'abc5db6f-5a2c-4650-aec1-ae19ad167ea0': 'MCD15A3H-006-FparExtra-QC-Statistics-QA.csv',
 '60e2faf9-3283-44fc-985b-a2285e1f8c16': 'MOD11A2-061-QC-Day-Statistics-QA.csv',
 '3d5af245-0844-4abc-a522-97f3d6ff2828': 'MOD11A2-061-QC-Night-Statistics-QA.csv',
 '3a4265d2-0f0c-4e83-ba35-b7b5743aede2': 'SRTMGL1-NUMNC-003-SRTMGL1-NUM-Statistics-QA.csv',
 'e336ec32-d2c2-4c41-b96c-135db49f3342': 'MCD15A3H-006-Statistics.csv',
 'f0334a15-20cf-413e-89c0-1f039c60762a': 'MOD11A2-061-Statistics.csv',
 '917619e6-5890-484f-8e58-8238660cb503': 'SRTMGL1-NC-003-Statistics.csv',
 '986f4160-a696-4fb5-832a-9984a986f9d0': 'NPS-Vegetation-Area-granule-list.txt',
 '4ba2c9f2-bb98-496f-94c0-f27aba97e0e5': 'NPS-Vegetation-Area-request.json',
 'b3df0fcc-c628-4815-82d7-d53218a46610': 'NPS-Vegetation-Area-MCD15A3H-006-metadata.xml',
 'd46129c7-711a-4112-a1b7-6eb031c6380f': 'NPS-Vegetation-Area-MOD11A2-061-metadata.xml',
 'c2fac1f5-38ed-44fb-b083-7471dc5c97b2': 'NPS-Vegetation-Area-SRTMGL1-NC-003-metadata.xml',
 '49407a8c-892c-4e14-b03d-d4570083335f': 'README.md'}

Use the files dictionary and a for loop to automate downloading all of the output files into the output directory.

for f in files:
    dl = r.get('{}bundle/{}/{}'.format(api, task_id, f), headers=head, stream=True, allow_redirects = 'True')                                # Get a stream to the bundle file
    if files[f].endswith('.tif'):
        filename = files[f].split('/')[1]
    else:
        filename = files[f] 
    filepath = os.path.join(destDir, filename)                                                       # Create output file path
    with open(filepath, 'wb') as f:                                                                  # Write file to dest dir
        for data in dl.iter_content(chunk_size=8192): f.write(data) 
print('Downloaded files can be found at: {}'.format(destDir))

Downloaded files can be found at: D:/appeears-api-getting-started/NPS Vegetation Area

5. Explore AρρEEARS Quality Service [Quality API]

The quality API provides quality details about all of the data products available in AρρEEARS. Below are examples of how to query the quality API for listing quality products, layers, and values. The final example (Section 5c.) demonstrates how AρρEEARS quality services can be leveraged to decode pertinent quality values for your data.

First, reset pagination to include offset which allows you to set the number of results to skip before starting to return entries. Next, make a call to list all of the data product layers and the associated quality product and layer information.

params = {'limit': 6, 'pretty': True, 'offset': 20}                     # Limit response to 6 entries, start w/ 20th entry, return pretty json
quality_response = r.get('{}quality'.format(api), params=params).json() # Call quality API using pagination and return json
quality_response   

[{'ProductAndVersion': 'CU_LT05.001',
  'Layer': 'SRB1',
  'QualityProductAndVersion': 'CU_LT05.001',
  'QualityLayers': ['PIXELQA'],
  'Continuous': False,
  'VisibleToWorker': True},
 {'ProductAndVersion': 'CU_LT05.001',
  'Layer': 'SRB2',
  'QualityProductAndVersion': 'CU_LT05.001',
  'QualityLayers': ['PIXELQA'],
  'Continuous': False,
  'VisibleToWorker': True},
 {'ProductAndVersion': 'CU_LT05.001',
  'Layer': 'SRB3',
  'QualityProductAndVersion': 'CU_LT05.001',
  'QualityLayers': ['PIXELQA'],
  'Continuous': False,
  'VisibleToWorker': True},
 {'ProductAndVersion': 'CU_LT05.001',
  'Layer': 'SRB4',
  'QualityProductAndVersion': 'CU_LT05.001',
  'QualityLayers': ['PIXELQA'],
  'Continuous': False,
  'VisibleToWorker': True},
 {'ProductAndVersion': 'CU_LT05.001',
  'Layer': 'SRB5',
  'QualityProductAndVersion': 'CU_LT05.001',
  'QualityLayers': ['PIXELQA'],
  'Continuous': False,
  'VisibleToWorker': True},
 {'ProductAndVersion': 'CU_LT05.001',
  'Layer': 'SRB7',
  'QualityProductAndVersion': 'CU_LT05.001',
  'QualityLayers': ['PIXELQA'],
  'Continuous': False,
  'VisibleToWorker': True}]

5a. List Quality Layers [List Quality Layers]

This API call will list all of the quality layer information for a product.

product = 'MCD15A3H.006'                                        # Product used in the example
ql_response = r.get('{}quality/{}'.format(api,product)).json()  # Call API to retrieve quality layers for selected product
ql_response                                                     # Print response

[{'ProductAndVersion': 'MCD15A3H.006',
 'Layer': 'Fpar_500m',
 'QualityProductAndVersion': 'MCD15A3H.006',
 'QualityLayers': ['FparLai_QC', 'FparExtra_QC'],
 'VisibleToWorker': True},
 {'ProductAndVersion': 'MCD15A3H.006',
 'Layer': 'FparStdDev_500m',
 'QualityProductAndVersion': 'MCD15A3H.006',
 'QualityLayers': ['FparLai_QC', 'FparExtra_QC'],
 'VisibleToWorker': True},
 {'ProductAndVersion': 'MCD15A3H.006',
 'Layer': 'Lai_500m',
 'QualityProductAndVersion': 'MCD15A3H.006',
 'QualityLayers': ['FparLai_QC', 'FparExtra_QC'],
 'VisibleToWorker': True},
 {'ProductAndVersion': 'MCD15A3H.006',
 'Layer': 'LaiStdDev_500m',
 'QualityProductAndVersion': 'MCD15A3H.006',
 'QualityLayers': ['FparLai_QC', 'FparExtra_QC'],
 'VisibleToWorker': True}]

5b. Show Quality Values [List Quality Values]

This API call will list all of the values for a given quality layer.

qlayer = ql_response[1]['QualityLayers'][0]                                # Set quality layer from ql_response for 'Lai_500m'
qv_response = r.get('{}quality/{}/{}'.format(api, product, qlayer)).json() # Call API for list of bit-word quality values
qv_response                                                                # Print response

[{'ProductAndVersion': 'MCD15A3H.006',
  'QualityLayer': 'FparLai_QC',
  'Name': 'MODLAND',
  'Value': 0,
  'Description': 'Good quality (main algorithm with or without saturation)',
  'Acceptable': True},
 {'ProductAndVersion': 'MCD15A3H.006',
  'QualityLayer': 'FparLai_QC',
  'Name': 'MODLAND',
  'Value': 1,
  'Description': 'Other Quality (back-up algorithm or fill values)',
  'Acceptable': False},
 {'ProductAndVersion': 'MCD15A3H.006',
  'QualityLayer': 'FparLai_QC',
  'Name': 'Sensor',
  'Value': 0,
  'Description': 'Terra',
  'Acceptable': None},
 {'ProductAndVersion': 'MCD15A3H.006',
  'QualityLayer': 'FparLai_QC',
  'Name': 'Sensor',
  'Value': 1,
  'Description': 'Aqua',
  'Acceptable': None},
 {'ProductAndVersion': 'MCD15A3H.006',
  'QualityLayer': 'FparLai_QC',
  'Name': 'DeadDetector',
  'Value': 0,
  'Description': 'Detectors apparently fine for up to 50% of channels 1, 2',
  'Acceptable': None},
 {'ProductAndVersion': 'MCD15A3H.006',
  'QualityLayer': 'FparLai_QC',
  'Name': 'DeadDetector',
  'Value': 1,
  'Description': 'Dead detectors caused >50% adjacent detector retrieval',
  'Acceptable': None},
 {'ProductAndVersion': 'MCD15A3H.006',
  'QualityLayer': 'FparLai_QC',
  'Name': 'CloudState',
  'Value': 0,
  'Description': 'Significant clouds NOT present (clear)',
  'Acceptable': None},
 {'ProductAndVersion': 'MCD15A3H.006',
  'QualityLayer': 'FparLai_QC',
  'Name': 'CloudState',
  'Value': 1,
  'Description': 'Significant clouds WERE present',
  'Acceptable': None},
 {'ProductAndVersion': 'MCD15A3H.006',
  'QualityLayer': 'FparLai_QC',
  'Name': 'CloudState',
  'Value': 2,
  'Description': 'Mixed cloud present in pixel',
  'Acceptable': None},
 {'ProductAndVersion': 'MCD15A3H.006',
  'QualityLayer': 'FparLai_QC',
  'Name': 'CloudState',
  'Value': 3,
  'Description': 'Cloud state not defined, assumed clear',
  'Acceptable': None},
 {'ProductAndVersion': 'MCD15A3H.006',
  'QualityLayer': 'FparLai_QC',
  'Name': 'SCF_QC',
  'Value': 0,
  'Description': 'Main (RT) method used, best result possible (no saturation)',
  'Acceptable': None},
 {'ProductAndVersion': 'MCD15A3H.006',
  'QualityLayer': 'FparLai_QC',
  'Name': 'SCF_QC',
  'Value': 1,
  'Description': 'Main (RT) method used with saturation. Good, very usable',
  'Acceptable': None},
 {'ProductAndVersion': 'MCD15A3H.006',
  'QualityLayer': 'FparLai_QC',
  'Name': 'SCF_QC',
  'Value': 2,
  'Description': 'Main (RT) method failed due to bad geometry, empirical algorithm used',
  'Acceptable': None},
 {'ProductAndVersion': 'MCD15A3H.006',
  'QualityLayer': 'FparLai_QC',
  'Name': 'SCF_QC',
  'Value': 3,
  'Description': 'Main (RT) method failed due to problems other than geometry, empirical algorithm used',
  'Acceptable': None},
 {'ProductAndVersion': 'MCD15A3H.006',
  'QualityLayer': 'FparLai_QC',
  'Name': 'SCF_QC',
  'Value': 4,
  'Description': "Pixel not produced at all, value couldn't be retrieved (possible reasons: bad L1B data, unusable MOD09GA data)",
  'Acceptable': None}]

5c. Decode Quality Values [Decode Quality Values]

This API call will decode the bits for a given quality value.

val = 1                                                                            # Set a specific value
q_response = r.get('{}quality/{}/{}/{}'.format(api, product, qlayer, val)).json()  # Call quality API for specific value
q_response                                                                         # Print response

{'Binary Representation': '0b00000001',
 'MODLAND': {'bits': '0b1',
  'description': 'Other Quality (back-up algorithm or fill values)'},
 'Sensor': {'bits': '0b0', 'description': 'Terra'},
 'DeadDetector': {'bits': '0b0',
  'description': 'Detectors apparently fine for up to 50% of channels 1, 2'},
 'CloudState': {'bits': '0b00',
  'description': 'Significant clouds NOT present (clear)'},
 'SCF_QC': {'bits': '0b000',
  'description': 'Main (RT) method used, best result possible (no saturation)'}}

6. BONUS: Import Request Output and Visualize

Here, import one of the output GeoTIFFs and show some basic visualizations using the matplotlib package.

# Import packages
import matplotlib.pyplot as plt
import numpy as np
from osgeo import gdal
list(files.values())  # List files downloaded

['MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_Lai_500m_doy2017181_aid0001.tif',
'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_Lai_500m_doy2017185_aid0001.tif',
'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_Lai_500m_doy2017189_aid0001.tif',
'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_Lai_500m_doy2017193_aid0001.tif',
'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_Lai_500m_doy2017197_aid0001.tif',
'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_Lai_500m_doy2017201_aid0001.tif',
'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_Lai_500m_doy2017205_aid0001.tif',
'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_Lai_500m_doy2017209_aid0001.tif',
'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparLai_QC_doy2017181_aid0001.tif',
'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparLai_QC_doy2017185_aid0001.tif',
'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparLai_QC_doy2017189_aid0001.tif',
'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparLai_QC_doy2017193_aid0001.tif',
'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparLai_QC_doy2017197_aid0001.tif',
'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparLai_QC_doy2017201_aid0001.tif',
'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparLai_QC_doy2017205_aid0001.tif',
'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparLai_QC_doy2017209_aid0001.tif',
'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparExtra_QC_doy2017181_aid0001.tif',
'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparExtra_QC_doy2017185_aid0001.tif',
'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparExtra_QC_doy2017189_aid0001.tif',
'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparExtra_QC_doy2017193_aid0001.tif',
'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparExtra_QC_doy2017197_aid0001.tif',
'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparExtra_QC_doy2017201_aid0001.tif',
'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparExtra_QC_doy2017205_aid0001.tif',
'MCD15A3H.006_2017179_to_2017212/MCD15A3H.006_FparExtra_QC_doy2017209_aid0001.tif',
'MOD11A2.061_2017175_to_2017212/MOD11A2.061_LST_Day_1km_doy2017177_aid0001.tif',
'MOD11A2.061_2017175_to_2017212/MOD11A2.061_LST_Day_1km_doy2017185_aid0001.tif',
'MOD11A2.061_2017175_to_2017212/MOD11A2.061_LST_Day_1km_doy2017193_aid0001.tif',
'MOD11A2.061_2017175_to_2017212/MOD11A2.061_LST_Day_1km_doy2017201_aid0001.tif',
'MOD11A2.061_2017175_to_2017212/MOD11A2.061_LST_Day_1km_doy2017209_aid0001.tif',
'MOD11A2.061_2017175_to_2017212/MOD11A2.061_LST_Night_1km_doy2017177_aid0001.tif',
'MOD11A2.061_2017175_to_2017212/MOD11A2.061_LST_Night_1km_doy2017185_aid0001.tif',
'MOD11A2.061_2017175_to_2017212/MOD11A2.061_LST_Night_1km_doy2017193_aid0001.tif',
'MOD11A2.061_2017175_to_2017212/MOD11A2.061_LST_Night_1km_doy2017201_aid0001.tif',
'MOD11A2.061_2017175_to_2017212/MOD11A2.061_LST_Night_1km_doy2017209_aid0001.tif',
'MOD11A2.061_2017175_to_2017212/MOD11A2.061_QC_Day_doy2017177_aid0001.tif',
'MOD11A2.061_2017175_to_2017212/MOD11A2.061_QC_Day_doy2017185_aid0001.tif',
'MOD11A2.061_2017175_to_2017212/MOD11A2.061_QC_Day_doy2017193_aid0001.tif',
'MOD11A2.061_2017175_to_2017212/MOD11A2.061_QC_Day_doy2017201_aid0001.tif',
'MOD11A2.061_2017175_to_2017212/MOD11A2.061_QC_Day_doy2017209_aid0001.tif',
'MOD11A2.061_2017175_to_2017212/MOD11A2.061_QC_Night_doy2017177_aid0001.tif',
'MOD11A2.061_2017175_to_2017212/MOD11A2.061_QC_Night_doy2017185_aid0001.tif',
'MOD11A2.061_2017175_to_2017212/MOD11A2.061_QC_Night_doy2017193_aid0001.tif',
'MOD11A2.061_2017175_to_2017212/MOD11A2.061_QC_Night_doy2017201_aid0001.tif',
'MOD11A2.061_2017175_to_2017212/MOD11A2.061_QC_Night_doy2017209_aid0001.tif',
'SRTMGL1_NC.003_2000001_to_2022084/SRTMGL1_NC.003_SRTMGL1_DEM_doy2000042_aid0001.tif',
 'SRTMGL1_NUMNC.003_2000001_to_2022084/SRTMGL1_NUMNC.003_SRTMGL1_NUM_doy2000042_aid0001.tif',
 'MCD15A3H-006-FparLai-QC-lookup.csv',
 'MCD15A3H-006-FparExtra-QC-lookup.csv',
 'MOD11A2-061-QC-Day-lookup.csv',
 'MOD11A2-061-QC-Night-lookup.csv',
 'SRTMGL1-NUMNC-003-SRTMGL1-NUM-lookup.csv',
 'MCD15A3H-006-FparLai-QC-Statistics-QA.csv',
 'MCD15A3H-006-FparExtra-QC-Statistics-QA.csv',
 'MOD11A2-061-QC-Day-Statistics-QA.csv',
 'MOD11A2-061-QC-Night-Statistics-QA.csv',
 'SRTMGL1-NUMNC-003-SRTMGL1-NUM-Statistics-QA.csv',
 'MCD15A3H-006-Statistics.csv',
 'MOD11A2-061-Statistics.csv',
 'SRTMGL1-NC-003-Statistics.csv',
 'NPS-Vegetation-Area-granule-list.txt',
 'NPS-Vegetation-Area-request.json',
 'NPS-Vegetation-Area-MCD15A3H-006-metadata.xml',
 'NPS-Vegetation-Area-MOD11A2-061-metadata.xml',
 'NPS-Vegetation-Area-SRTMGL1-NC-003-metadata.xml',
 'README.md']

6a. Import a GeoTIFF

To perform the next step below, you will need to have GDAL installed on your OS. Open the GeoTIFF file for the SRTM DEM, and read in as an array.

dem = gdal.Open(destDir + '/SRTMGL1_NC.003_SRTMGL1_DEM_doy2000042_aid0001.tif' ) # Read file in
demBand = dem.GetRasterBand(1)                                          # Read the band (layer)
demData = demBand.ReadAsArray().astype('float')                         # Import band as an array with type float

Next, query the metadata for the fill value, and set fill value equal to nan.

demFill = demBand.GetNoDataValue()            # Returns fill value
demData[demData == demFill] = np.nan          # Set fill value to nan

6b. Plot a GeoTIFF

In this section, begin by highlighting the functionality of the matplotlib plotting package.

# Set matplotlib plots inline
%matplotlib inline

First, make a basic plot of the DEM data.

plt.imshow(demData);  # Visualize a basic plot of the DEM data

SRTM DEM over the Grand Canyon.

Next, add some additional parameters to the plot.

fig = plt.figure(figsize = (10,7.5))  # Set the figure size (x,y)
plt.axis('off')                       # Remove the axes' values
ax = fig.add_subplot(111)             

# Plot the array, using a colormap and setting a custom linear stretch based on the min/max Elevation values
plt.imshow(demData, vmin = np.nanmin(demData), vmax = np.nanmax(demData), cmap = 'terrain');

SRTM DEM over the Grand Canyon.

Finally, add important map items including a legend and title.

plt.style.use("dark_background")                                                       # Default to a black background
fig2 = plt.figure(figsize=(10,7.5))                                                    # Set the figure size
plt.axis('off')                                                                        # Remove the axes' values
ax1 = fig2.add_subplot(111)                                                            # Make a subplot
fig2.subplots_adjust(top=3.8)                                                          # Adjust spacing
ax1.set_title('SRTM DEM: Grand Canyon NP',fontsize=15,fontweight='bold',color='white') # Add title

# Plot the masked data, using a colormap and setting a custom linear stretch based on the min/max DEM values
im = plt.imshow(demData, vmin = np.nanmin(demData), vmax = np.nanmax(demData), cmap = 'terrain');

cb = plt.colorbar(im, orientation='horizontal', fraction=0.047, pad=0.004, shrink=0.6) # Add a colormap legend
cb.set_label(label='Elevation (m)', color = 'white')                                   # Set Label and color
cb.outline.set_edgecolor('white')                                                      # Set edge color

SRTM DEM over the Grand Canyon.

This example can provide a template to use for your own research workflows. Leveraging the AρρEEARS API for searching, extracting, and formatting analysis ready data, and importing it directly into Python means that you can keep your entire research workflow in a single software program, from start to finish.

Contact Information

Material written by Cole Krehbiel1

Contact: LPDAAC@usgs.gov Voice: +1-605-594-6116 Organization: Land Processes Distributed Active Archive Center (LP DAAC) Website: https://lpdaac.usgs.gov/ Date last modified: 05-04-2022 1Innovate! Inc., contractor to the U.S. Geological Survey, Earth Resources Observation and Science (EROS) Center, Sioux Falls, South Dakota, 57198-001, USA. Work performed under USGS contract G15PD00467 for LP DAAC2. 2LP DAAC Work performed under NASA contract NNG14HH33I.

Relevant Products

Product Long Name
MCD15A2H.006 MODIS/Terra+Aqua Leaf Area Index/FPAR 8-Day L4 Global 500 m SIN Grid
SRTMGL1.003 NASA Shuttle Radar Topography Mission Global 1 arc second
MOD11A2.061 MODIS/Terra Land Surface Temperature/Emissivity 8-Day L3 Global 1 km SIN Grid

Tools

Name Filters Description
AppEEARS Decode Quality, Order, Search, Subset

The Application for Extracting and Exploring Analysis Ready Samples (AρρE…
47914 252nd Street | Sioux Falls, SD 57198-0001
Voice: 605-594-6116 | Toll Free: 866-573-3222 | Fax: 605-594-6963
lpdaac@usgs.gov