R Client Library for SpatioTemporal Asset Catalog (rstac)
STAC is a specification of files and web services used to describe geospatial information assets. The specification can be consulted in https://stacspec.org/.
R client library for STAC (
rstac) was designed to fully support STAC
API v1.0.0. It also supports earlier versions (>= v0.8.0).
# install via CRAN install.packages("rstac")
To install the development version of
rstac, run the following
# load necessary libraries library(devtools) install_github("brazil-data-cube/rstac")
library(rstac) library(magrittr) # for pipe (%>%) in examples
rstac implements the following STAC endpoints:
| STAC endpoints |
rstac functions | API version |
| :------------------------------------------- | :--------------------------- | :---------- |
stac() | >= 0.9.0 |
stac() | \< 0.9.0 |
collections() | >= 0.9.0 |
collections(collection_id) | >= 0.9.0 |
items() | >= 0.9.0 |
items(feature_id) | >= 0.9.0 |
stac_search() | >= 0.9.0 |
stac_search() | \< 0.9.0 |
These functions can be used to retrieve information from a STAC API
service. The code bellow creates a
stac object and list the available
collections of the STAC API of the Brazil Data
Cube project of the Brazilian National
Space Research Institute INPE.
s_obj <- stac("https://brazildatacube.dpi.inpe.br/stac/") get_request(s_obj) #> ###STACCatalog #> - id: bdc #> - description: Brazil Data Cube Catalog #> - field(s): description, id, stac_version, links
s_obj stores information to connect to the Brazil Data
Cube STAC web service. The
get_request method makes a HTTP GET
connection to it and retrieves a STAC Catalog document from the server.
links entry is an available collection that can be accessed via
In the code bellow, we get some STAC items of
collection that intersects the bounding box passed to the
parameter. To do this, we call the
stac_search function that
implements the STAC
/search endpoint. The returned document is a STAC
Item Collection (a geojson containing a feature collection).
it_obj <- s_obj %>% stac_search(collections = "CB4_64_16D_STK-1", bbox = c(-47.02148, -12.98314, -42.53906, -17.35063)) %>% get_request() it_obj #> ###STACItemCollection #> - matched feature(s): 236 #> - features (10 item(s)): #> - CB4_64_16D_STK_v001_022024_2021-02-02_2021-02-17 #> - CB4_64_16D_STK_v001_022025_2021-02-02_2021-02-17 #> - CB4_64_16D_STK_v001_022024_2021-01-17_2021-02-01 #> - CB4_64_16D_STK_v001_022025_2021-01-17_2021-02-01 #> - CB4_64_16D_STK_v001_022024_2021-01-01_2021-01-16 #> - CB4_64_16D_STK_v001_022025_2021-01-01_2021-01-16 #> - CB4_64_16D_STK_v001_022024_2020-12-18_2020-12-31 #> - CB4_64_16D_STK_v001_022025_2020-12-18_2020-12-31 #> - CB4_64_16D_STK_v001_022024_2020-12-02_2020-12-17 #> - CB4_64_16D_STK_v001_022025_2020-12-02_2020-12-17 #> - field(s): type, links, context, features
rstac uses the httr package to
manage HTTP requests, allowing the use of tokens from the authorization
protocols OAuth 1.0 or 2.0 as well as other configuration options. In
the code below, we present an example of how to pass a parameter token
on a HTTP request.
it_obj <- s_obj %>% stac_search(collections = "CB4_64_16D_STK-1", bbox = c(-47.02148, -12.98314, -42.53906, -17.35063)) %>% get_request(add_headers("x-api-key" = "MY-TOKEN"))
In addition to the functions mentioned above, the
provides some extra functions for handling items and to bulk download
rstac provides some functions to facilitates the interaction with STAC
data. In the example bellow, we get how many items matched the search
# it_obj variable from the last code example it_obj %>% items_matched() #>  236
However, if we count how many items there are in
it_obj variable, we
10, meaning that more items could be fetched from the STAC
it_obj %>% items_length() #>  10
# fetch all items from server # (but don't stored them back in it_obj) it_obj %>% items_fetch(progress = FALSE) %>% items_length() #>  236
All we’ve got in previous example was metadata to STAC Items, including
links to geospatial data called
assets. To download all
assets in a
STAC Item Collection we can use
assets_download() function, that
returns an update STAC Item Collection referring to the downloaded
assets. The code bellow downloads the
thumbnail assets (.png files) of
10 items stored in
download_items <- it_obj %>% assets_download(assets_name = "thumbnail")
rstac package was implemented based on an extensible architecture,
so feel free to contribute by implementing new STAC API
based on the STAC API specifications.
ext_subclass) for your extension in
RSTACQueryfunction constructor, and implement the S3 generics methods:
after_response. Using these S3 generics methods you can define how parameters must be submitted to the HTTP request and the types of the returned documents responses. See the implemented ext_query API extension as an example.
You can get a full explanation about each STAC (v1.0.0) endpoint at
A detailed documentation with examples on how to use each endpoint and
other functions available in the
rstac package can be obtained by
?rstac in R console.
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.