i.landsat.download - GRASS GIS manual

Note: This document is for an older version of GRASS GIS that has been discontinued. You should upgrade, and read the current manual page.

NAME

i.landsat.download - Downloads Landsat TM, ETM and OLI data from EarthExplorer using landsatxplore library

KEYWORDS

imagery, satellite, Landsat, download

SYNOPSIS

i.landsat.download

i.landsat.download --help

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] [--help] [--verbose] [--quiet] [--ui]

Flags:

-l: List filtered products and exit
--help: Print usage summary
--verbose: Verbose module output
--quiet: Quiet module output
--ui: Force launching GUI dialog

Parameters:

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; Options: planetary_computer, usgs; Default: planetary_computer
clouds=integer: Maximum cloud cover percentage for Landsat scene; Default: 100
dataset=string: Landsat dataset to search for; Options: 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; Options: RT, T1, T2
sort=string[,string,...]: Sort by values in given order; Options: acquisition_date, cloud_cover; Default: cloud_cover,acquisition_date
order=string: Sort order (see sort parameter); Options: asc, desc; Default: asc
timeout=integer: Download timeout in seconds; Default: 300
limit=integer: maximum number of Landsat scenes; Default: 50

DESCRIPTION
NOTES
EXAMPLES
REQUIREMENTS
SEE ALSO
AUTHOR

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 here, and then view their keys by signing in with their Microsoft account here.

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)

Accessed: Saturday Feb 22 06:04:50 2025