Query and download Landsat data from EarthExplorer API

[quinten]

I have now also implemented a simple query and download system to use EarthExplorer to get Landsat (4/5/7/8/9) data that can be used in ACOLITE processing. This system is now integrated in the ACOLITE code on GitHub and can be freely tested. There are other packages that do a similar thing, e.g. landsatxplore.

[Edit 2024-04-27] I have now moved the earthexplorer module into ac.api, so change the call in the examples below from ac.earthexplorer to ac.api.earthexplorer

To use the EarthExplorer feature please make an account at https://earthexplorer.usgs.gov/ and put your credentials in your .netrc file:

Code: Select all

machine earthexplorer
login YOUR_LOGIN
password YOUR_PASSWORD

Make sure your .netrc file has no group or world read access, i.e. -rw-------. You can set this for example by:

Code: Select all

chmod 600 ~/.netrc

Alternatively you can set EARTHEXPLORER_u=YOUR_LOGIN and EARTHEXPLORER_p=YOUR_PASSWORD in either your OS environment variables or in the acolite/config/config.txt file.

After importing ACOLITE:

Code: Select all

import sys, os
user_home = os.path.expanduser("~")
sys.path.append(user_home+'/git/acolite')
import acolite as ac

You can query based on a region of interest (either a WKT string, polygon file or ACOLITE S,W,N,E limit) for a specific sensor type ("tm" for L4/5, "etm" for L7, and "ot" for L8/9). By default "ot", i.e. OLI/TIRS on L8/9 is used. The following example lists urls and scene names with <20% cloud cover over the Blue Accelerator platform near Oostende, Belgium using a simple point WKT:

Code: Select all

entity_list, identifier_list, dataset_list = ac.api.earthexplorer.query(
    roi='POINT (2.9192711575039305 51.24648601469525)',
    landsat_type = 'ot', start_date = '2023-07-01', end_date = '2023-08-31', cloud_cover = 20)

Note that the cloud cover parameter is the scene wide fraction (0-100) as provided by USGS processing. Scenes with unknown cloud cover are excluded when the cloud_cover filter is active.

These urls/scenes can then be downloaded to a specific directory:

Code: Select all

local_scenes = ac.api.earthexplorer.download(entity_list, dataset_list, identifier_list, output = None)

If output is set to None, scenes will be downloaded in the current working directory, and you may prefer to specify another path to store downloaded scenes. By default the tar files are extracted and deleted after extraction. This can be switched off by passing extract_tar=False and delete_tar=False.

A sample run of the last two examples in a Jupyter notebook after downloading and extracting one of the found scenes:

EarthExplorer_d.png (126.26 KiB) Viewed 42544 times

The paths to the local scenes can then be passed to ACOLITE processing, i.e. using ac.acolite.acolite_run(), see for example here.

[quinten]

An alternative option is to have ACOLITE download a specific scene directly from EarthExplorer, by specifying the scene name as the inputfile, and setting scene_download to True. If the local path does not exist, EartExplorer will be queried for the scene. For example, to download and process a specific scene with ACOLITE, in a text settings file:

Code: Select all

inputfile=LC08_L1TP_200024_20210529_20210608_02_T1
output=full path to output location
scene_download=True

or by using ac.acolite.acolite_run():

Code: Select all

import sys, os
user_home = os.path.expanduser("~")
sys.path.append(user_home+'/git/acolite')
import acolite as ac

settings = {}
settings['inputfile'] = 'LC08_L1TP_200024_20210529_20210608_02_T1'
settings['output'] = full path to output location
settings['scene_download']=True

ac.acolite.acolite_run(settings)

You can also specify the local storage directory with scene_download_directory if it should be different than the main output directory. If the requested scene (extracted or not) is already present in that directory it should not be downloaded again.

A sample run of the last example with also setting a limit over the Spuikom in Oostende and scene_download_directory in a Jupyter notebook:

scene_download_landsat.png (146.12 KiB) Viewed 42527 times

[quinten]

I have implemented download of ECOSTRESS data using this API. Please use the keyword ecostress_type instead of landsat_type. Data types 'eco1bgeo', 'eco1brad', 'eco1bmaprad' are supported. For example:

Code: Select all

import sys, os
user_home = os.path.expanduser("~")
sys.path.append(user_home+'/git/acolite')
import acolite as ac

entity_list, identifier_list, dataset_list = ac.api.earthexplorer.query(
    roi='POINT (0.2818 51.1322)', ecostress_type = 'eco1bmaprad', 
    start_date =  '2023-10-10', end_date =  '2023-10-10')

local_scenes = ac.api.earthexplorer.download(entity_list, dataset_list, identifier_list, output = None)

Note that you can change the download directory by providing the path as output to the download function.

[quinten]

Please note the changes from ac.earthexplorer to ac.api.earthexplorer in the messages above!