getSpatialData (version 0.0.4)

getLandsat_query: Query Landsat records

Description

getLandsat_query queries the USGS Earth Explorer for Landsat data by some basic input search parameters. The function returns a data frame that can be further filtered.

Usage

getLandsat_query(time_range, name = "all", aoi = NULL,
  username = NULL, password = NULL, ..., verbose = TRUE)

Arguments

time_range

character, containing two elements: the query's starting date and stopping date, formatted "YYYY-MM-DD", e.g. "2017-05-15"

name

character, optional. Identifies the name of the product to be queried. If set to "all" (default), every available Landsat product is searched for results and included in the output. Use getLandsat_names to revcieve a vector with all available Landsat products from Earth Explorer, if you want to select a specific one.

aoi

sfc_POLYGON or SpatialPolygons or matrix, representing a single multi-point (at least three points) polygon of your area-of-interest (AOI). If it is a matrix, it has to have two columns (longitude and latitude) and at least three rows (each row representing one corner coordinate). If its projection is not +proj=longlat +datum=WGS84 +no_defs, it is reprojected to the latter. Use set_aoi instead to once define an AOI globally for all queries within the running session. If aoi is undefined, the AOI that has been set using set_aoi is used.

username

character, a valid user name to the USGS EROS Registration System (ERS). If NULL (default), the session-wide login credentials are used (see login_USGS for details on registration).

password

character, the password to the specified user account. If NULL (default) and no seesion-wide password is defined, it is asked interactively ((see login_USGS for details on registration).

...

one of the following filters by which the collected records should be filtered before return:

• level_filter, character, filtering records by processing level. Either "all" for all levels (default) or a vector of levels

• maxCloudScene, numeric, filtering records by maximum scene cloud coverage (in percent). Default is 100.

• maxCloudLand, numeric, filtering records by maximum land cloud coverage (in percent). Default is 100.

verbose

logical, whether to display details on the function's progress or output on the console.

Value

A data frame of found records. Each row represents one record. The data frame can be further filtered by its columnwise attributes. The selected rows can be handed over to the other getLandsat functions for previewing or downloading.

See Also

getLandsat_names getLandsat_preview getLandsat_data

Examples

# NOT RUN {
## Load packages
library(getSpatialData)
library(sf)

## set aoi and time range for the query
set_aoi(aoi_data[[1]])
time_range <-  c("2017-08-01", "2017-08-30")

## Login to USGS ERS
# }
# NOT RUN {
login_USGS("username")

## set archive directory
set_archive("/path/to/archive/")

## get available products and select one
product_names <- getLandsat_names()

## query for records for your AOI, time range and product
query <- getLandsat_query(time_range = time_range, name = product_names[7])

## preview a record
getLandsat_preview(query[5,])

#print available levels for a record
query[5,]$levels_available

## download record 5 with level "l1" (will direct to AWS automaticaly)
files <- getLandsat_data(records = query[5,], level = "l1", source = "auto")

## download record 5 with level "sr" (will be processed on demand by ESPA)
files <- getLandsat_data(records = query[5,], level = "sr", source = "auto")
# this can take very long, since the function will wait,
# until the processing by ESPA is done

## you can abort the function while it is waiting for ESPA and resume later:
files <- getLandsat_data(espa_order = "[e-mail]-YOUR-ORDER-ID")
# the order IDs are displayed and send by mail, use them to resume the task
# }
# NOT RUN {
# }