i.landsat.download

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

Command linePython (grass.tools)Python (grass.script)

i.landsat.download [-l] [settings=name] [output=name] [map=name] [datasource=string] [clouds=integer] [dataset=string] [start=string] [end=string] [id=string [,string,...]] [tier=string [,string,...]] [sort=string [,string,...]] [order=string] [timeout=integer] [limit=integer] [--verbose] [--quiet] [--qq] [--ui]

Example:

i.landsat.download

grass.tools.Tools.i_landsat_download(settings=None, output=None, map=None, datasource="planetary_computer", clouds=100, dataset="landsat_9_ot_c2_l2", start=None, end=None, id=None, tier=None, sort="cloud_cover,acquisition_date", order="asc", timeout=300, limit=50, flags=None, verbose=None, quiet=None, superquiet=None)

Example:

tools = Tools()
tools.i_landsat_download()

This grass.tools API is experimental in version 8.5 and expected to be stable in version 8.6.

grass.script.run_command("i.landsat.download", settings=None, output=None, map=None, datasource="planetary_computer", clouds=100, dataset="landsat_9_ot_c2_l2", start=None, end=None, id=None, tier=None, sort="cloud_cover,acquisition_date", order="asc", timeout=300, limit=50, flags=None, verbose=None, quiet=None, superquiet=None)

Example:

gs.run_command("i.landsat.download")

Parameters

Command linePython (grass.tools)Python (grass.script)

settings=name
    Full path to settings file (user, password)
    '-' for standard input
output=name
    Name for output directory where to store downloaded Landsat data
map=name
    Name of input vector map to define Area of Interest (AOI)
    If not given then current computational extent is used
datasource=string
    Data source to use for searching and downloading landsat scenes
    Allowed values: planetary_computer, usgs
    Default: planetary_computer
clouds=integer
    Maximum cloud cover percentage for Landsat scene
    Default: 100
dataset=string
    Landsat dataset to search for
    Allowed values: landsat_tm_c2_l1, landsat_tm_c2_l2, landsat_etm_c2_l1, landsat_etm_c2_l2, landsat_8_ot_c2_l1, landsat_8_ot_c2_l2, landsat_9_ot_c2_l1, landsat_9_ot_c2_l2
    Default: landsat_9_ot_c2_l2
start=string
    Start date ('YYYY-MM-DD')
end=string
    End date ('YYYY-MM-DD')
id=string [,string,...]
    List of scenes IDs to download
tier=string [,string,...]
    Tiers
    Allowed values: RT, T1, T2
sort=string [,string,...]
    Sort by values in given order
    Allowed values: acquisition_date, cloud_cover
    Default: cloud_cover,acquisition_date
order=string
    Sort order (see sort parameter)
    Allowed values: asc, desc
    Default: asc
timeout=integer
    Download timeout in seconds
    Default: 300
limit=integer
    maximum number of Landsat scenes
    Default: 50
-l
    List filtered products and exit
--help
    Print usage summary
--verbose
    Verbose module output
--quiet
    Quiet module output
--qq
    Very quiet module output
--ui
    Force launching GUI dialog

settings : str | io.StringIO, optional
    Full path to settings file (user, password)
    '-' for standard input
    Used as: input, file, name
output : str, optional
    Name for output directory where to store downloaded Landsat data
    Used as: input, dir, name
map : str, optional
    Name of input vector map to define Area of Interest (AOI)
    If not given then current computational extent is used
    Used as: input, vector, name
datasource : str, optional
    Data source to use for searching and downloading landsat scenes
    Allowed values: planetary_computer, usgs
    Default: planetary_computer
clouds : int, optional
    Maximum cloud cover percentage for Landsat scene
    Default: 100
dataset : str, optional
    Landsat dataset to search for
    Allowed values: landsat_tm_c2_l1, landsat_tm_c2_l2, landsat_etm_c2_l1, landsat_etm_c2_l2, landsat_8_ot_c2_l1, landsat_8_ot_c2_l2, landsat_9_ot_c2_l1, landsat_9_ot_c2_l2
    Default: landsat_9_ot_c2_l2
start : str, optional
    Start date ('YYYY-MM-DD')
end : str, optional
    End date ('YYYY-MM-DD')
id : str | list[str], optional
    List of scenes IDs to download
tier : str | list[str], optional
    Tiers
    Allowed values: RT, T1, T2
sort : str | list[str], optional
    Sort by values in given order
    Allowed values: acquisition_date, cloud_cover
    Default: cloud_cover,acquisition_date
order : str, optional
    Sort order (see sort parameter)
    Allowed values: asc, desc
    Default: asc
timeout : int, optional
    Download timeout in seconds
    Default: 300
limit : int, optional
    maximum number of Landsat scenes
    Default: 50
flags : str, optional
    Allowed values: l
    l
        List filtered products and exit
verbose : bool, optional
    Verbose module output
    Default: None
quiet : bool, optional
    Quiet module output
    Default: None
superquiet : bool, optional
    Very quiet module output
    Default: None

Returns:

result : grass.tools.support.ToolResult | None
If the tool produces text as standard output, a ToolResult object will be returned. Otherwise, None will be returned.

Raises:

grass.tools.ToolError: When the tool ended with an error.

settings : str, optional
    Full path to settings file (user, password)
    '-' for standard input
    Used as: input, file, name
output : str, optional
    Name for output directory where to store downloaded Landsat data
    Used as: input, dir, name
map : str, optional
    Name of input vector map to define Area of Interest (AOI)
    If not given then current computational extent is used
    Used as: input, vector, name
datasource : str, optional
    Data source to use for searching and downloading landsat scenes
    Allowed values: planetary_computer, usgs
    Default: planetary_computer
clouds : int, optional
    Maximum cloud cover percentage for Landsat scene
    Default: 100
dataset : str, optional
    Landsat dataset to search for
    Allowed values: landsat_tm_c2_l1, landsat_tm_c2_l2, landsat_etm_c2_l1, landsat_etm_c2_l2, landsat_8_ot_c2_l1, landsat_8_ot_c2_l2, landsat_9_ot_c2_l1, landsat_9_ot_c2_l2
    Default: landsat_9_ot_c2_l2
start : str, optional
    Start date ('YYYY-MM-DD')
end : str, optional
    End date ('YYYY-MM-DD')
id : str | list[str], optional
    List of scenes IDs to download
tier : str | list[str], optional
    Tiers
    Allowed values: RT, T1, T2
sort : str | list[str], optional
    Sort by values in given order
    Allowed values: acquisition_date, cloud_cover
    Default: cloud_cover,acquisition_date
order : str, optional
    Sort order (see sort parameter)
    Allowed values: asc, desc
    Default: asc
timeout : int, optional
    Download timeout in seconds
    Default: 300
limit : int, optional
    maximum number of Landsat scenes
    Default: 50
flags : str, optional
    Allowed values: l
    l
        List filtered products and exit
verbose : bool, optional
    Verbose module output
    Default: None
quiet : bool, optional
    Quiet module output
    Default: None
superquiet : bool, optional
    Very quiet module output
    Default: None

DESCRIPTION

i.landsat.download allows to search and download Landsat TM, ETM and OLI data from USGS EarthExplorer and Planetary Computer using EODAG Python library.

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):

Landsat 5 (TM): 1984 to 2013
Landsat 7 (ETM+): 1999 to present (note: Landsat 7 ETM+ SLC-off error after May 31, 2003)
Landsat 8 (OLI): 2013 to present
Landsat 9 (OLI-2): 2021 to present

The dataset names and IDs are:

Dataset Name	Dataset ID
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 2 Level 1	`landsat_etm_c2_l1`
Landsat 7 ETM+ Collection 2 Level 2	`landsat_etm_c2_l2`
Landsat 8 Collection 2 Level 1	`landsat_8_ot_c2_l1`
Landsat 8 Collection 2 Level 2	`landsat_8_ot_c2_l2`
Landsat 9 Collection 2 Level 1	`landsat_9_ot_c2_l1`
Landsat 9 Collection 2 Level 2	`landsat_9_ot_c2_l2`

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 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 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).

NOTES

Settings

i.landsat.download reads the user credentials either from the terminal or from the settings file. This file must contain two lines in case of USGS provider, or one line in case of Planetary Computer provider.

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

Alternatively, if the settings option is not specified i.landsat.download will attempt to use credentials stored in the default EODAG configuration file in $HOME/.config/eodag/eodag.yml. Note any parameter set in the configuration file, e.g. 'extract' to specify whether to extract the downloaded scenes or not, will be used by i.landsat.download, unless overriden by user options. Exception: output parameter in EODAG configuration file is not used by i.landsat.download, and the default output directory is the current working directory.

USGS EarthExplorer

To connect to EarthExplorer both a username and a password are required. See the register page for signing up.

USGS settings file:

myusername
mypassword

USGS interactive settings:

Insert username: myusername
Insert password:

Planetary Computer

Most datasets are anonymously accessible, but a subscription key may be needed to increase rate limits and access private datasets. Users can create an account, and then view their keys by signing in with their Microsoft account.

Planetary computer settings file:

apikey

Planetary computer interactive settings:

Insert API key:

Note: to use Plantery Computer anonymously the settings option should not be used.

EXAMPLES

Search available scenes:

i.landsat.download -l settings=credentials.txt \
    dataset=landsat_8_ot_c2_l2 clouds=15 \
    datasource=usgs start='2018-08-24' end='2018-12-21'

Download all available scenes:

i.landsat.download settings=credentials.txt \
    dataset=landsat_8_ot_c2_l2 clouds=15 \
    datasource=usgs start='2018-08-24' end='2018-12-21' \
    timeout=600

Download selected scenes by ID anonymously from Planetary Computer:

i.landsat.download datasource=planetary_computer \
    id=LC09_L2SP_015035_20240529_02_T1,LC09_L2SP_015035_20240614_02_T1 \
    output=/tmp

REQUIREMENTS

EODAG library (install with pip install eodag)

AUTHOR

Veronica Andreo, CONICET, Argentina.

SOURCE CODE

Available at: i.landsat.download source code (history)
Latest change: Monday Jun 22 12:53:40 2026 in commit 425b037

i.landsat.download

Parameters

DESCRIPTION

NOTES

Settings

USGS EarthExplorer

Planetary Computer

EXAMPLES

REQUIREMENTS

SEE ALSO

AUTHOR

SOURCE CODE