rstac (version 1.0.1)

stac_search: Endpoint functions

Description

(This document is based on STAC specification documentation https://github.com/radiantearth/stac-spec/ and reproduces some of its parts)

The stac_search function implements /stac/search API endpoint (v0.8.1) and /search (v0.9.0 or v1.0.0). It prepares query parameters used in the search API request, a stac object with all filter parameters to be provided to get_request or post_request functions. The GeoJSON content returned by these requests is a doc_items object, a regular R list representing a STAC Item Collection document.

Usage

stac_search(
  q,
  collections = NULL,
  ids = NULL,
  bbox = NULL,
  datetime = NULL,
  intersects = NULL,
  limit = NULL
)

Value

A rstac_query object with the subclass search containing all search field parameters to be provided to STAC API web service.

Arguments

q

a rstac_query object expressing a STAC query criteria.

collections

a character vector of collection IDs to include in the search for items. Only items in one of the provided collections will be searched.

ids

a character vector with item IDs. All other filters parameters that further restrict the number of search results are ignored.

bbox

a numeric vector with only features that have a geometry that intersects the bounding box are selected. The bounding box is provided as four or six numbers, depending on whether the coordinate reference system includes a vertical axis (elevation or depth):

• Lower left corner, coordinate axis 1

• Lower left corner, coordinate axis 2

• Lower left corner, coordinate axis 3 (optional)

• Upper right corner, coordinate axis 1

• Upper right corner, coordinate axis 2

• Upper right corner, coordinate axis 3 (optional)

The coordinate reference system of the values is WGS84 longitude/latitude (http://www.opengis.net/def/crs/OGC/1.3/CRS84). The values are, in most cases, the sequence of minimum longitude, minimum latitude, maximum longitude, and maximum latitude. However, in cases where the box spans the antimeridian, the first value (west-most box edge) is larger than the third value (east-most box edge).

datetime

a character with a date-time or an interval. Date and time strings needs to conform to RFC 3339. Intervals are expressed by separating two date-time strings by '/' character. Open intervals are expressed by using '..' in place of date-time.

Examples:

• A date-time: "2018-02-12T23:20:50Z"

• A closed interval: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z"

• Open intervals: "2018-02-12T00:00:00Z/.." or "../2018-03-18T12:31:12Z"

Only features that have a datetime property that intersects the interval or date-time informed in datetime are selected.

intersects

a list expressing GeoJSON geometries objects as specified in RFC 7946. Only returns items that intersect with the provided geometry. To turn a GeoJSON into a list the package jsonlite can be used.

limit

an integer defining the maximum number of results to return. If not informed, it defaults to the service implementation.

See Also

stac(), ext_query(), get_request(), post_request()

Examples

if (FALSE) {
 # GET request
 stac("https://brazildatacube.dpi.inpe.br/stac/") %>%
  stac_search(collections = "CB4-16D-2", limit = 10,
         datetime = "2017-08-01/2018-03-01") %>%
  get_request()

 # POST request
 stac("https://brazildatacube.dpi.inpe.br/stac/") %>%
  stac_search(collections = "CB4-16D-2",
         bbox = c(-47.02148, -17.35063, -42.53906, -12.98314)) %>%
  post_request()
}