GRASS logo

NAME - Downloads Landsat TM, ETM and OLI data from EarthExplorer using landsatxplore library


imagery, satellite, Landsat, download

SYNOPSIS --help [-l] settings=name [output=name] [map=name] [clouds=integer] [dataset=string] [start=string] [end=string] [id=string[,string,...]] [tier=string[,string,...]] [sort=string[,string,...]] [order=string] [timeout=integer] [limit=integer] [--help] [--verbose] [--quiet] [--ui]


List filtered products and exit
Print usage summary
Verbose module output
Quiet module output
Force launching GUI dialog


settings=name [required]
Full path to settings file (user, password)
'-' for standard input
Name for output directory where to store downloaded Landsat data
Name of input vector map to define Area of Interest (AOI)
If not given then current computational extent is used
Maximum cloud cover percentage for Landsat scene
Landsat dataset to search for
Options: landsat_tm_c1, landsat_etm_c1, landsat_8_c1, landsat_tm_c2_l1, landsat_tm_c2_l2, landsat_etm_c2_l1, landsat_etm_c2_l2, landsat_ot_c2_l1, landsat_ot_c2_l2
Default: landsat_8_c1
Start date ('YYYY-MM-DD')
End date ('YYYY-MM-DD')
List of scenes IDs to download
Options: RT, T1, T2
Sort by values in given order
Options: acquisition_date, cloud_cover
Default: cloud_cover,acquisition_date
Sort order (see sort parameter)
Options: asc, desc
Default: asc
Download timeout in seconds
Default: 300
maximum number of Landsat scenes
Default: 50

Table of contents

DESCRIPTION allows to search and download Landsat TM, ETM and OLI data from USGS EarthExplorer through the landsatxplore Python library. Datasets currently supported include Collection 1 and Collection 2.

Landsat data are organized in tiers: Newly-acquired Landsat scenes are placed in the Real-Time (RT) tier. After reprocessing they are transitioned to either Tier 1 (T1; scenes with the highest available data quality, considered suitable for time-series analysis) or Tier 2 (T2; less accurate geometry). The Tier designation (T1, T2, RT) is indicated at the end of the Landsat Product Identifier.

The supported Landsat satellites include (see also Landsat satellite chronology):

The dataset names and IDs are:
Dataset Name Dataset ID
Landsat 5 TM Collection 1 Level 1 landsat_tm_c1
Landsat 5 TM Collection 2 Level 1 landsat_tm_c2_l1
Landsat 5 TM Collection 2 Level 2 landsat_tm_c2_l2
Landsat 7 ETM+ Collection 1 Level 1 landsat_etm_c1
Landsat 7 ETM+ Collection 2 Level 1 landsat_etm_c2_l1
Landsat 7 ETM+ Collection 2 Level 2 landsat_etm_c2_l2
Landsat 8 Collection 1 Level 1 landsat_8_c1
Landsat 8 Collection 2 Level 1 landsat_ot_c2_l1
Landsat 8 Collection 2 Level 2 landsat_ot_c2_l2

To connect to EarthExplorer both a user name and a password are required. See the register page for signing up. reads the user credentials either from the terminal or from the settings file. This file must contain two lines:


User credentials can be also defined interactively when settings=- is given. Note that interactive prompt does not work in the graphical user interface.

Insert username: myusername
Insert password:

By default, only products which footprint intersects current computation region extent (area of interest, AOI) are filtered. The AOI can be optionally defined by a vector map. In this case, the vector extent will be used as AOI.

To only list available scenes, l flag must be set. If no start or end dates are provided, the module will search scenes from the past 60 days.

To download all scenes found within the time frame provided, the user must remove the l flag and provide an output directory. Otherwise, files will be downloaded into /tmp directory. To download only selected scenes, one or more IDs must be provided through the id option, along with the settings file and an output directory. In addition, a timeout (in seconds) can be set to define how long a request should wait for a response before aborting (default is 300 seconds).


Search available scenes: -l settings=credentials.txt \
    dataset=landsat_8_c1 clouds=15 \
    start='2018-08-24' end='2018-12-21'
Download all available scenes: settings=credentials.txt \
    dataset=landsat_8_c1 clouds=15 \
    start='2018-08-24' end='2018-12-21' \
Download selected scenes by ID: settings=credentials.txt \
    id=LC81391162018338LGN00,LC81301172018339LGN00 \



Overview of i.landsat tools

i.landsat.import,, i.landsat.toar

Landsat Collection 1 info

Landsat Collection 2 info


Veronica Andreo, CONICET, Argentina.


Available at: source code (history)

Latest change: Wed Sep 1 13:38:21 2021 in commit: 78e390f693ad3a6ec9a0004b5e2e1f62b70024d8

Main index | Imagery index | Topics index | Keywords index | Graphical index | Full index

© 2003-2022 GRASS Development Team, GRASS GIS 7.8.7dev Reference Manual