espa_inventory_search: espa_inventory_search
In espa.tools: Wrappers for the USGS ESPA APIs and Earth Explorer

Description Usage Arguments Details Value Author(s) References See Also Examples

R wrapper for USGS/EROS Inventory Service Scene Search API. Note: earthexplorer_search is much easier to use, and is recommended.

espa_inventory_search(datasetName, spatialFilter = "", temporalFilter = "",
  months = "", includeUnknownCloudCover = T, minCloudCover = 0,
  maxCloudCover = 100, additionalCriteria = "", maxResults = 50000,
  startingNumber = 1, sortOrder = "ASC", apiKey, lowerLeft = "",
  upperRight = "", startDate = "1920-01-07", endDate = Sys.Date(),
  verbose = F)

`datasetName`	Character. Used as a filter with wildcards inserted at the beginning and the end of the supplied value. See https://mapbox.github.io/usgs/reference/catalog/hdds.html for a list of valid datasetNames.
`spatialFilter`	List. Used to apply a spatial filter on the data.
`temporalFilter`	List. Used to apply a temporal filter on the data.
`months`	Numeric. Used to limit results to specific months.
`includeUnknownCloudCover`	Logical. Used to determine if scenes with unknown cloud cover values should be included in the results. Default is TRUE.
`minCloudCover`	Numeric. Used to limit results by minimum cloud cover (for supported datasets). Range 0 to 100. Default is 0.
`maxCloudCover`	Numeric. Used to limit results by maximum cloud cover (for supported datasets). Range 0 to 100. Default is 100.
`additionalCriteria`	List. Used to filter results based on dataset specific metadata fields. Use datasetFields request to determine available fields and options.
`maxResults`	Numeric. Used to determine the number of results to return Use with startingNumber for controlled pagination. Maximum list size - 50,000
`startingNumber`	Numeric. Used to determine the result number to start returning from Use with maxResults for controlled pagination.
`sortOrder`	Character. Used to order results based on acquisition date. Default="ASC".
`apiKey`	Character. Users API Key/Authentication Token, obtained from espa_inventory_login request.
`lowerLeft`	List. When used in conjunction with upperRight, creates a bounding box to search spatially. Should be a list of form list(latitude=XX,longitude=XX)
`upperRight`	List. When used in conjunction with lowerLeft, creates a bounding box to search spatially. Should be a list of form list(latitude=XX,longitude=XX)
`startDate`	Character. Used to search datasets temporally for possible dataset coverage. ISO 8601 Formatted Date. Time portion is ignored. Default is "1920-01-01".
`endDate`	Character. Used to search datasets temporally for possible dataset coverage. ISO 8601 Formatted Date. Time portion is ignored.Default is today's date.
`verbose`	Logical. Verbose execution? Default=F.

Searching is done with limited search criteria. All coordinates are assumed decimal-degree format. If lowerLeft or upperRight are supplied, then both must exist in the request to complete the bounding box. Starting and ending dates, if supplied, are used as a range to search data based on acquisition dates. The current implementation will only search at the date level, discarding any time information. If data in a given dataset is composite data, or data acquired over multiple days, a search will be done to match any intersection of the acquisition range. There currently is a 50,000 scene limit for the number of results that are returned, however, some client applications may encounter timeouts for large result sets for some datasets. To use the additional criteria field, pass one of the four search filter objects (SearchFilterAnd, SearchFilterBetween, SearchFilterOr, SearchFilterValue) in JSON format with additionalCriteria being the root element of the object.

Additional Criteria Usage: Additional criteria fields can be used to add metadata level filters to search results. This feature allows to creation of complex logical queries by allowing users to nest the 'and/or' logical operators, however, users should expect longer search times as these queries may take longer to execute. To obtain a datasets list of criteria fields, a datasetFields request must be executed. The response of this request will list all of the possible criteria fields. Some criteria fields include 'display lists'. These are lists of values that correspond to predefined values of interest within the dataset. In some cases their name and value are the same, but the value should be used at all times, as that value corresponds to the database values that will be searched on. When using the operand 'like', no wildcards are needed. The search will append the appropriate database wildcards and the beginning and end of the supplied value automatically. For all operands dealing with alphabetic values please note that searches are case sensitive. The second example below would result in the following query logic (using Landsat 8 dataset) (WRS Path BETWEEN 22 AND 24) AND (WRS Row BETWEEN 38 AND 40)

Number of hits found given the search.

Jonathan A. Greenberg (espa-tools@estarcion.net) (wrapper) and USGS ESPA Developers (API and documentation)

https://earthexplorer.usgs.gov/inventory/documentation/json-api#search

espa_inventory_login,espa_inventory_get_api

## Not run:  
# Get API KEY (required EROS username/password): 
apiKey=espa_inventory_login("myusername","mypassword")

# Standard search:
espa_inventory_search(datasetName="LANDSAT_8",
		"lowerLeft"=list(latitude=75,longitude=-135),
		"upperRight"=list(latitude=90,longitude=-120),
		startDate="2006-01-01",endDate="2007-12-01",
		maxResults=3,startingNumber=1,sortOrder="ASC",
		apiKey=apiKey)

# Additional Criteria Usage:
espa_inventory_search(datasetName="LANDSAT_8",
		additionalCriteria=list(
				filterType="and",
				childFilters=c(
						list(filterType="between",fieldId=10036,
							firstValue="22",secondValue="24"),
						list(filterType="between",fieldId=10038,
							firstValue="38",secondValue="40")
						)),
						node="EE",
						maxResults=3,startingNumber=1,sortOrder="ASC",
						apiKey=apiKey)

## End(Not run)