# rstac R Client Library for SpatioTemporal Asset Catalog (rstac) [](https://github.com/brazil-data-cube/rstac/blob/master/LICENSE) [](https://github.com/brazil-data-cube/rstac/actions/workflows/R-CMD-check.yaml) [](https://ci.appveyor.com/project/OldLipe/rstac) [](https://app.codecov.io/gh/brazil-data-cube/rstac) [](https://lifecycle.r-lib.org/articles/stages.html) [](https://cran.r-project.org/package=rstac) [](https://github.com/radiantearth/stac-api-spec) [](https://discord.com/channels/689541907621085198#) STAC is a specification of files and web services used to describe geospatial information assets. The specification can be consulted at . The R client library for STAC (`rstac`) was designed to fully support STAC API v1.0.0. It also supports earlier versions (\>= v0.8.0). ## Installation ``` r # install via CRAN install.packages("rstac") ``` ### Development version To install the development version of `rstac`, run the following command: ``` r remotes::install_github("brazil-data-cube/rstac") ``` Load the `rstac` package: ``` r library(rstac) ``` ## Usage `rstac` supports the following STAC endpoints: | **STAC** endpoints | `rstac` functions | API version | |:---|:---|:---| | `/` | `stac()` | \>= 0.9.0 | | `/stac` | `stac()` | \< 0.9.0 | | `/collections` | `collections()` | \>= 0.9.0 | | `/collections/{collectionId}` | `collections(collection_id)` | \>= 0.9.0 | | `/collections/{collectionId}/items` | `items()` | \>= 0.9.0 | | `/collections/{collectionId}/items/{itemId}` | `items(feature_id)` | \>= 0.9.0 | | `/search` | `stac_search()` | \>= 0.9.0 | | `/stac/search` | `stac_search()` | \< 0.9.0 | | `/conformance` | `conformance()` | \>= 0.9.0 | | `/collections/{collectionId}/queryables` | `queryables()` | \>= 1.0.0 | These functions can be used to retrieve information from a STAC API service. The code below creates a `stac` object and lists the available collections of the STAC API of the [Brazil Data Cube](https://data.inpe.br/bdc/en/home-page-2/) project of the Brazilian National Space Research Institute (INPE). ``` r s_obj <- stac("https://data.inpe.br/bdc/stac/v1/") get_request(s_obj) #> ###Catalog #> - id: INPE #> - description: #> This is the landing page for the INPE STAC server. The SpatioTemporal Asset Catalogs (STAC) provide a standardized way to expose collections of spatial temporal data. Here you will find collections of data provided by projects and areas of INPE. #> - field(s): type, title, description, id, stac_version, links, conformsTo ``` The variable `s_obj` stores the information needed to connect to the Brazil Data Cube STAC web service. The `get_request` method makes an HTTP GET request and retrieves a STAC Catalog document from the server. Each `links` entry refers to an available collection that can be accessed via the STAC API. In the code below, we get some STAC items from the `CB4-16D-2` collection that intersects the bounding box passed to the `bbox` parameter. To do this, we call the `stac_search` function, which implements the STAC `/search` endpoint. The returned document is a STAC Item Collection (a `GeoJSON` containing a feature collection). ``` r it_obj <- s_obj %>% stac_search(collections = "CB4-16D-2", bbox = c(-47.02148, -17.35063, -42.53906, -12.98314), limit = 100) %>% get_request() it_obj #> ###Items #> - matched feature(s): 0 #> - features (0 item(s) / 0 not fetched): #> - assets: #> - item's fields: ``` `rstac` uses the [`httr`](https://github.com/r-lib/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 token in an HTTP request header. ``` r it_obj <- s_obj %>% stac_search(collections = "CB4-16D-2", bbox = c(-47.02148, -17.35063, -42.53906, -12.98314)) %>% get_request(add_headers("x-api-key" = "MY-TOKEN")) ``` In addition to the functions mentioned above, the `rstac` package provides additional functions for handling items and bulk-downloading assets. ### Item functions `rstac` provides functions that facilitate interaction with STAC data. In the example below, we get how many items matched the search criteria: ``` r # it_obj variable from the last code example it_obj %>% items_matched() #> [1] 0 ``` However, `items_length()` counts only the items currently stored in `it_obj`. If this value is smaller than `items_matched()`, more items can be fetched from the STAC service: ``` r it_obj %>% items_length() #> [1] 0 ``` ``` r # fetch all items from server # (and store them back in `it_obj`) it_obj <- it_obj %>% items_fetch(progress = FALSE) it_obj %>% items_length() #> [1] 0 ``` ### Download assets All we got in the previous example was metadata for STAC Items, including links to geospatial data called `assets`. To download all `assets` in a STAC Item Collection, you can use `assets_download()`, which returns an updated STAC Item Collection referring to the downloaded assets. The code below downloads the `thumbnail` assets (`.png` files) of up to `10` items stored in `it_obj`. ``` r download_items <- it_obj %>% assets_download(assets_name = "thumbnail", items_max = 10) ``` ### `CQL2` query filter `rstac` also supports advanced query filtering using the Common Query Language (`CQL2`). Users can write complex filter expressions using R code in an easy and natural way. For a complete list of supported operators and helper functions, see `?ext_filter`. ``` r s_obj <- stac("https://planetarycomputer.microsoft.com/api/stac/v1") it_obj <- s_obj %>% ext_filter( collection == "sentinel-2-l2a" && `s2:vegetation_percentage` >= 50 && `eo:cloud_cover` <= 10 && `s2:mgrs_tile` == "20LKP" && anyinteracts(datetime, interval("2020-06-01", "2020-09-30")) ) %>% post_request() ``` ## Getting help You can get a full explanation of each STAC (v1.0.0) endpoint at [STAC API spec](https://github.com/radiantearth/stac-api-spec/tree/master/ogcapi-features). Detailed documentation with examples on how to use each endpoint and other functions available in the `rstac` package can be obtained by typing `?rstac` in the R console. ## Citation To cite `rstac` in publications, use: R. Simoes, F. C. de Souza, M. Zaglia, G. R. de Queiroz, R. D. C. dos Santos and K. R. Ferreira, “Rstac: An R Package to Access Spatiotemporal Asset Catalog Satellite Imagery,” 2021 IEEE International Geoscience and Remote Sensing Symposium IGARSS, 2021, pp. 7674-7677, doi: 10.1109/IGARSS47720.2021.9553518. ## Acknowledgments for financial support We acknowledge and thank the project funders that provided financial and material support: - Amazon Fund, established by the Brazilian government with financial contribution from Norway, through the project contract between the Brazilian Development Bank (BNDES) and the Foundation for Science, Technology and Space Applications (FUNCATE), for the establishment of the Brazil Data Cube, process 17.2.0536.1. - Radiant Earth Foundation and STAC Project Steering Committee for advancing the STAC ecosystem. - OpenGeoHub Foundation and the European Commission (EC) through the project Open-Earth-Monitor Cyberinfrastructure: Environmental information to support EU’s Green Deal (1 Jun. 2022 – 31 May 2026 - 101059548) ## How to contribute The `rstac` package was implemented based on an extensible architecture, so feel free to contribute by implementing new STAC API [extensions/fragments](https://github.com/radiantearth/stac-api-spec/tree/master/fragments) based on the STAC API specifications. 1. Fork the project by creating a [fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo). 2. Create a file inside the `R/` directory called `ext_{extension_name}.R`. 3. In the code, specify a subclass name (e.g., `my_subclass`) for your extension and use it when calling [`rstac_query()`](https://github.com/brazil-data-cube/rstac/blob/master/R/query-funs.R). You also need to implement the following S3 generic methods for your subclass: [`before_request()`](https://github.com/brazil-data-cube/rstac/blob/master/R/extensions.R), [`after_response()`](https://github.com/brazil-data-cube/rstac/blob/master/R/extensions.R), and [`parse_params()`](https://github.com/brazil-data-cube/rstac/blob/master/R/extensions.R). With these S3 generic methods, you can define how parameters are submitted in HTTP requests and how returned documents are parsed. See the implemented [`ext_filter`](https://github.com/brazil-data-cube/rstac/blob/master/R/ext_filter.R) API extension as an example. 4. Make a [Pull Request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request) against the most recent [development branch](https://github.com/brazil-data-cube/rstac/).