Introduction to rstac package

About rstac

This document will introduce the concepts of the rstac package. rstac is an R client library for STAC that fully supports STAC API v1.0.0 and its earlier versions (>= v0.8.0).

The table shows the functions implemented by the rstac package according to the STAC API endpoints. For each endpoint, rstac has a specialized implementation.

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

The rstac package makes the requests explicitly. The rstac pipeline creates the endpoints with function concatenations and then requests them.

Getting started

Let’s start by installing the rstac package:

install.packages("rstac")

Creating queries

This tutorial use the STAC API made available by the Brazil Data Cube (BDC) project. BDC is a research, development, and technological innovation project of the National Institute for Space Research (INPE), Brazil.

Let’s start by loading rstac and creating a query for the BDC catalog.

library(rstac)

s_obj <- stac("https://brazildatacube.dpi.inpe.br/stac/")
s_obj
#> ###rstac_query
#> - url: https://brazildatacube.dpi.inpe.br/stac/
#> - params:
#> - field(s): version, base_url, endpoint, params, verb, encode

The rstac_query object stores the metadata of the created query. This metadata can be accessed as a list element during query creation.

s_obj$base_url
#> [1] "https://brazildatacube.dpi.inpe.br/stac/"

Endpoints are constructed through function concatenations provided by rstac. Some examples are shown below:

s_obj %>% 
  collections()
#> ###rstac_query
#> - url: https://brazildatacube.dpi.inpe.br/stac/
#> - params:
#> - field(s): version, base_url, endpoint, params, verb, encode

s_obj %>% 
  collections("S2-16D-2")
#> ###rstac_query
#> - url: https://brazildatacube.dpi.inpe.br/stac/
#> - params:
#>   - collection_id: S2-16D-2
#> - field(s): version, base_url, endpoint, params, verb, encode

s_obj %>% 
  collections("S2-16D-2") %>%
  items()
#> ###rstac_query
#> - url: https://brazildatacube.dpi.inpe.br/stac/
#> - params:
#>   - collection_id: S2-16D-2
#> - field(s): version, base_url, endpoint, params, verb, encode

s_obj %>% 
  collections("S2-16D-2") %>% 
  items(feature_id = "S2-16D_V2_015011_20190117")
#> ###rstac_query
#> - url: https://brazildatacube.dpi.inpe.br/stac/
#> - params:
#>   - collection_id: S2-16D-2
#>   - feature_id: S2-16D_V2_015011_20190117
#> - field(s): version, base_url, endpoint, params, verb, encode

s_obj %>% 
  stac_search(collections = c("CB4-16D-2", "S2-16D-2")) %>%
  ext_query("bdc:tile" == "007004")
#> ###rstac_query
#> - url: https://brazildatacube.dpi.inpe.br/stac/
#> - params:
#>   - collections: CB4-16D-2,S2-16D-2
#>   - query: list(eq = "007004")
#> - field(s): version, base_url, endpoint, params, verb, encode

Making requests

rstac package supports GET and POST HTTP methods. With future updates to the STAC specifications, it is intended to support other methods such as PUT and DELETE. In addition, it is possible to add more configuration options to the request, such as headers (httr::add_headers()) and cookies (httr::set_cookies()). These options are available in the httr package documentation in the config.

HTTP GET: `get_request()`

s_obj %>%
  collections(collection_id = "CB4-16D-2") %>%
  items() %>%
  get_request() 
#> ###Items
#> - matched feature(s): 13258
#> - features (10 item(s) / 13248 not fetched):
#>   - CB4-16D_V2_000003_20240101
#>   - CB4-16D_V2_000002_20240101
#>   - CB4-16D_V2_001003_20240101
#>   - CB4-16D_V2_000004_20240101
#>   - CB4-16D_V2_001001_20240101
#>   - CB4-16D_V2_001002_20240101
#>   - CB4-16D_V2_002000_20240101
#>   - CB4-16D_V2_002004_20240101
#>   - CB4-16D_V2_002001_20240101
#>   - CB4-16D_V2_001004_20240101
#> - assets: 
#> BAND13, BAND14, BAND15, BAND16, CLEAROB, CMASK, EVI, NDVI, PROVENANCE, thumbnail, TOTALOB
#> - item's fields: 
#> assets, bbox, collection, geometry, id, links, properties, stac_extensions, stac_version, type

HTTP POST: `post_request()`

s_obj %>%
  stac_search(
    collections = c("CB4-16D-2", "S2-16D-2"),
    datetime = "2021-01-01/2021-01-31",
    limit = 400) %>%
  post_request()
#> ###Items
#> - matched feature(s): 1886
#> - features (400 item(s) / 1486 not fetched):
#>   - CB4-16D_V2_006009_20210117
#>   - CB4-16D_V2_006006_20210117
#>   - CB4-16D_V2_006007_20210117
#>   - CB4-16D_V2_006008_20210117
#>   - CB4-16D_V2_006003_20210117
#>   - CB4-16D_V2_006004_20210117
#>   - CB4-16D_V2_006005_20210117
#>   - CB4-16D_V2_006001_20210117
#>   - CB4-16D_V2_006002_20210117
#>   - CB4-16D_V2_006000_20210117
#>   - ... with 390 more feature(s).
#> - assets: 
#> B01, B02, B03, B04, B05, B06, B07, B08, B09, B11, B12, B8A, BAND13, BAND14, BAND15, BAND16, CLEAROB, CMASK, EVI, NBR, NDVI, PROVENANCE, SCL, thumbnail, TOTALOB
#> - item's fields: 
#> assets, bbox, collection, geometry, id, links, properties, stac_extensions, stac_version, type

Example of providing an additional argument to HTTP verb in a request:

s_obj %>% 
  stac_search(collections = c("CB4-16D-2", "S2-16D-2")) %>%
  post_request(config = c(httr::add_headers("x-api-key" = "MY-KEY")))
#> ###Items
#> - matched feature(s): 129101
#> - features (10 item(s) / 129091 not fetched):
#>   - CB4-16D_V2_000003_20240101
#>   - CB4-16D_V2_000002_20240101
#>   - CB4-16D_V2_001003_20240101
#>   - CB4-16D_V2_000004_20240101
#>   - CB4-16D_V2_001001_20240101
#>   - CB4-16D_V2_001002_20240101
#>   - CB4-16D_V2_002000_20240101
#>   - CB4-16D_V2_002004_20240101
#>   - CB4-16D_V2_002001_20240101
#>   - CB4-16D_V2_001004_20240101
#> - assets: 
#> BAND13, BAND14, BAND15, BAND16, CLEAROB, CMASK, EVI, NDVI, PROVENANCE, thumbnail, TOTALOB
#> - item's fields: 
#> assets, bbox, collection, geometry, id, links, properties, stac_extensions, stac_version, type

Visualization of the documents

Each rstac object is mapped according to the endpoints of the STAC spec. In this way, each object has a different view. The format for viewing objects is in Markdown.

`STACCatalog` object

s_obj %>% 
  get_request()
#> ###Catalog
#> - id: bdc
#> - description: Brazil Data Cube Catalog
#> - field(s): description, id, stac_version, links

`STACCollection` object

s_obj %>%
  collections("S2-16D-2") %>%
  get_request()
#> ###Collection
#> - id: S2-16D-2
#> - title: Sentinel-2 - 10m - 16 days - v2
#> - description: 
#> This datacube was generated with all available surface reflectance images processed using Sen2cor. The data is provided with 10 meters of spatial resolution, reprojected and cropped to BDC_SM grid Version 2 (BDC_SM V2), considering a temporal compositing function of 16 days using the Least Cloud Cover First (LCF) best pixel approach.
#> - field(s): 
#> id, stac_version, stac_extensions, title, version, deprecated, description, bdc:public, links, license, properties, extent, bdc:bands_quicklook, bdc:metadata, bdc:grs, bdc:tiles, bdc:composite_function, bdc:type, cube:dimensions, bdc:crs, bdc:temporal_composition

`Item` object

s_obj %>%
  collections("CB4-16D-2") %>%
  items(feature_id = "CB4-16D_V2_000002_20230509") %>%
  get_request()
#> ###Item
#> - id: CB4-16D_V2_000002_20230509
#> - collection: CB4-16D-2
#> - bbox: 
#> xmin: -75.61346, ymin: -5.31845, xmax: -71.54176, ymax: -1.25475
#> - datetime: 2023-05-09T00:00:00
#> - assets: 
#> EVI, NDVI, CMASK, BAND13, BAND14, BAND15, BAND16, CLEAROB, TOTALOB, thumbnail, PROVENANCE
#> - item's fields: 
#> assets, bbox, collection, geometry, id, links, properties, stac_extensions, stac_version, type

`Items` object

s_obj %>% 
  stac_search(collections = c("CB4_64_16D_STK", "S2-16D-2")) %>%
  get_request()
#> ###Items
#> - matched feature(s): 115843
#> - features (10 item(s) / 115833 not fetched):
#>   - S2-16D_V2_001014_20220930
#>   - S2-16D_V2_002011_20220930
#>   - S2-16D_V2_002012_20220930
#>   - S2-16D_V2_002013_20220930
#>   - S2-16D_V2_002014_20220930
#>   - S2-16D_V2_002015_20220930
#>   - S2-16D_V2_002016_20220930
#>   - S2-16D_V2_003011_20220930
#>   - S2-16D_V2_003012_20220930
#>   - S2-16D_V2_003013_20220930
#> - assets: 
#> B01, B02, B03, B04, B05, B06, B07, B08, B09, B11, B12, B8A, CLEAROB, EVI, NBR, NDVI, PROVENANCE, SCL, thumbnail, TOTALOB
#> - item's fields: 
#> assets, bbox, collection, geometry, id, links, properties, stac_extensions, stac_version, type

Besides, the rstac package provides several auxiliary functions for Item and Items objects. These auxiliary functions operate at the item or asset level. Functions dedicated to items have the prefix items_. Otherwise, asset-oriented functions have the prefix assets_

Items functions

The Items object have some facilitating functions to manipulate/extract information, for example:

items_fields(): Lists fields names inside an item.
items_filter(): Performs a filter by items according to expressions operating on the properties of a Items object.
items_fetch(): Performs the pagination of items.
items_length(): Returns the number of items in an object.
items_matched(): Returns the number of items matching the search criteria.
items_assets(): Returns the assets name from Items and Item objects.

It is interesting to verify the fields of items before filtering:

s_obj %>%
  stac_search(
    collections = "CB4-16D-2",
    datetime = "2019-01-01/2019-12-31",
    limit = 100) %>% 
  post_request() %>%
  items_fields(field = "properties")
#>  [1] "bdc:tiles"      "created"        "datetime"       "end_datetime"  
#>  [5] "eo:bands"       "eo:cloud_cover" "eo:gsd"         "instruments"   
#>  [9] "platform"       "start_datetime" "updated"

Let’s filter items that have the percentage of clouds smaller than 10%:

s_obj %>%
  stac_search(
    collections = "CB4-16D-2",
    datetime = "2019-01-01/2019-12-31",
    limit = 100) %>% 
  post_request() %>%
  items_filter(properties$`eo:cloud_cover` < 10)
#> ###Items
#> - matched feature(s): 1656
#> - features (55 item(s) / 1601 not fetched):
#>   - CB4-16D_V2_006009_20191219
#>   - CB4-16D_V2_006006_20191219
#>   - CB4-16D_V2_006007_20191219
#>   - CB4-16D_V2_006008_20191219
#>   - CB4-16D_V2_006004_20191219
#>   - CB4-16D_V2_006005_20191219
#>   - CB4-16D_V2_007003_20191219
#>   - CB4-16D_V2_007004_20191219
#>   - CB4-16D_V2_007005_20191219
#>   - CB4-16D_V2_007006_20191219
#>   - ... with 45 more feature(s).
#> - assets: 
#> BAND13, BAND14, BAND15, BAND16, CLEAROB, CMASK, EVI, NDVI, PROVENANCE, thumbnail, TOTALOB
#> - item's fields: 
#> assets, bbox, collection, geometry, id, links, properties, stac_extensions, stac_version, type

Number of items returned in the query (in this case equal to the limit defined as parameter):

s_obj %>%
  stac_search(
    collections = "CB4-16D-2",
    datetime = "2019-01-01/2019-12-31",
    limit = 100) %>% 
  post_request() %>%
  items_length()
#> [1] 100

Number of matched items in the query:

s_obj %>%
  stac_search(
    collections = "CB4-16D-2",
    datetime = "2019-01-01/2019-12-31",
    limit = 100) %>%
  post_request() %>%
  items_matched()
#> [1] 1656

Paginating all items that were matched in the query:

items_fetched <- s_obj %>%
  stac_search(
    collections = "CB4-16D-2",
    datetime = "2019-01-01/2019-12-31",
    limit = 500) %>%
  post_request() %>%
  items_fetch(progress = FALSE)

items_fetched
#> ###Items
#> - matched feature(s): 1656
#> - features (1656 item(s) / 0 not fetched):
#>   - CB4-16D_V2_006009_20191219
#>   - CB4-16D_V2_006006_20191219
#>   - CB4-16D_V2_006007_20191219
#>   - CB4-16D_V2_006008_20191219
#>   - CB4-16D_V2_006003_20191219
#>   - CB4-16D_V2_006004_20191219
#>   - CB4-16D_V2_006005_20191219
#>   - CB4-16D_V2_006001_20191219
#>   - CB4-16D_V2_006002_20191219
#>   - CB4-16D_V2_006000_20191219
#>   - ... with 1646 more feature(s).
#> - assets: 
#> BAND13, BAND14, BAND15, BAND16, CLEAROB, CMASK, EVI, NDVI, PROVENANCE, thumbnail, TOTALOB
#> - item's fields: 
#> assets, bbox, collection, geometry, id, links, properties, stac_extensions, stac_version, type

Note that all items was fetched:

items_length(items_fetched)
#> [1] 1656

Listing the assets of the retrieved items:

items_assets(items_fetched)
#>  [1] "BAND13"     "BAND14"     "BAND15"     "BAND16"     "CLEAROB"   
#>  [6] "CMASK"      "EVI"        "NDVI"       "PROVENANCE" "thumbnail" 
#> [11] "TOTALOB"

Assets functions

assets_download(): Downloads the assets provided by the STAC API.
assets_url(): Returns a character vector with each asset href. For the URL you can add the GDAL library drivers for the following schemes:
- HTTP/HTTPS files;
- S3 (AWS S3);
- GS (Google Cloud Storage).
assets_select(): Selects the assets of each item by its name.
assets_rename(): Rename each asset using a named list or a function.

Listing the assets names of all items:

s_obj %>%
  stac_search(
    collections = "CB4-16D-2",
    datetime = "2019-01-01/2019-12-31",
    limit = 10) %>%
  post_request() %>%
  items_assets()
#>  [1] "BAND13"     "BAND14"     "BAND15"     "BAND16"     "CLEAROB"   
#>  [6] "CMASK"      "EVI"        "NDVI"       "PROVENANCE" "thumbnail" 
#> [11] "TOTALOB"

Selecting assets that have names "BAND14" and "NDVI"

selected_assets <- s_obj %>%
  stac_search(
    collections = "CB4-16D-2",
    datetime = "2019-01-01/2019-12-31",
    limit = 10) %>%
  post_request() %>%
  assets_select(asset_names = c("BAND14", "NDVI"))

items_assets(selected_assets)
#> [1] "BAND14" "NDVI"

Listing asset urls from the selected bands:

selected_assets %>% 
  assets_url()
#>  [1] "https://brazildatacube.dpi.inpe.br/cubes/composed/cb4-16d/v2/006/009/2019/12/19/CB4-16D_V2_006009_20191219_BAND14.tif"
#>  [2] "https://brazildatacube.dpi.inpe.br/cubes/composed/cb4-16d/v2/006/006/2019/12/19/CB4-16D_V2_006006_20191219_BAND14.tif"
#>  [3] "https://brazildatacube.dpi.inpe.br/cubes/composed/cb4-16d/v2/006/007/2019/12/19/CB4-16D_V2_006007_20191219_BAND14.tif"
#>  [4] "https://brazildatacube.dpi.inpe.br/cubes/composed/cb4-16d/v2/006/008/2019/12/19/CB4-16D_V2_006008_20191219_BAND14.tif"
#>  [5] "https://brazildatacube.dpi.inpe.br/cubes/composed/cb4-16d/v2/006/003/2019/12/19/CB4-16D_V2_006003_20191219_BAND14.tif"
#>  [6] "https://brazildatacube.dpi.inpe.br/cubes/composed/cb4-16d/v2/006/004/2019/12/19/CB4-16D_V2_006004_20191219_BAND14.tif"
#>  [7] "https://brazildatacube.dpi.inpe.br/cubes/composed/cb4-16d/v2/006/005/2019/12/19/CB4-16D_V2_006005_20191219_BAND14.tif"
#>  [8] "https://brazildatacube.dpi.inpe.br/cubes/composed/cb4-16d/v2/006/001/2019/12/19/CB4-16D_V2_006001_20191219_BAND14.tif"
#>  [9] "https://brazildatacube.dpi.inpe.br/cubes/composed/cb4-16d/v2/006/002/2019/12/19/CB4-16D_V2_006002_20191219_BAND14.tif"
#> [10] "https://brazildatacube.dpi.inpe.br/cubes/composed/cb4-16d/v2/006/000/2019/12/19/CB4-16D_V2_006000_20191219_BAND14.tif"
#> [11] "https://brazildatacube.dpi.inpe.br/cubes/composed/cb4-16d/v2/006/009/2019/12/19/CB4-16D_V2_006009_20191219_NDVI.tif"  
#> [12] "https://brazildatacube.dpi.inpe.br/cubes/composed/cb4-16d/v2/006/006/2019/12/19/CB4-16D_V2_006006_20191219_NDVI.tif"  
#> [13] "https://brazildatacube.dpi.inpe.br/cubes/composed/cb4-16d/v2/006/007/2019/12/19/CB4-16D_V2_006007_20191219_NDVI.tif"  
#> [14] "https://brazildatacube.dpi.inpe.br/cubes/composed/cb4-16d/v2/006/008/2019/12/19/CB4-16D_V2_006008_20191219_NDVI.tif"  
#> [15] "https://brazildatacube.dpi.inpe.br/cubes/composed/cb4-16d/v2/006/003/2019/12/19/CB4-16D_V2_006003_20191219_NDVI.tif"  
#> [16] "https://brazildatacube.dpi.inpe.br/cubes/composed/cb4-16d/v2/006/004/2019/12/19/CB4-16D_V2_006004_20191219_NDVI.tif"  
#> [17] "https://brazildatacube.dpi.inpe.br/cubes/composed/cb4-16d/v2/006/005/2019/12/19/CB4-16D_V2_006005_20191219_NDVI.tif"  
#> [18] "https://brazildatacube.dpi.inpe.br/cubes/composed/cb4-16d/v2/006/001/2019/12/19/CB4-16D_V2_006001_20191219_NDVI.tif"  
#> [19] "https://brazildatacube.dpi.inpe.br/cubes/composed/cb4-16d/v2/006/002/2019/12/19/CB4-16D_V2_006002_20191219_NDVI.tif"  
#> [20] "https://brazildatacube.dpi.inpe.br/cubes/composed/cb4-16d/v2/006/000/2019/12/19/CB4-16D_V2_006000_20191219_NDVI.tif"

Renaming assets using the pattern <old-name> = <new-name>

renamed_assets <- selected_assets %>% 
  assets_rename(BAND14 = "B14")
renamed_assets
#> ###Items
#> - matched feature(s): 1656
#> - features (10 item(s) / 1646 not fetched):
#>   - CB4-16D_V2_006009_20191219
#>   - CB4-16D_V2_006006_20191219
#>   - CB4-16D_V2_006007_20191219
#>   - CB4-16D_V2_006008_20191219
#>   - CB4-16D_V2_006003_20191219
#>   - CB4-16D_V2_006004_20191219
#>   - CB4-16D_V2_006005_20191219
#>   - CB4-16D_V2_006001_20191219
#>   - CB4-16D_V2_006002_20191219
#>   - CB4-16D_V2_006000_20191219
#> - assets: B14, NDVI
#> - item's fields: 
#> assets, bbox, collection, geometry, id, links, properties, stac_extensions, stac_version, type

In the assets field of the output it can be seen that the asset’s name has changed. It is also possible to check the asset names using the items_assets() function.

items_assets(renamed_assets)
#> [1] "B14"  "NDVI"

Asset preview

rstac also provides a helper function to plot preview assets (e.g. thumbnail and quicklook).

second_item <- items_fetched$features[[2]]
second_item %>%
  assets_url(asset_names = "thumbnail") %>%
  preview_plot()

Here, we selected the second item of items_fetched’s features and plotted its thumbnail asset.

Conclusion

The rstac package can be useful for querying and working with satellite imagery data from STAC APIs. It offers a simple interface for searching STAC items, exploring the results, and working with assets. Additional functions include reading and plotting preview images. This tutorial has provided a short introduction on how to use the package. For more about CQL2 in rstac, type the command ?ext_filter.

Rolf Simoes, Felipe Carvalho, and Gilberto Camara

2023-01-09

About rstac

Getting started

Creating queries

Making requests

HTTP GET: `get_request()`

HTTP POST: `post_request()`

Visualization of the documents

`STACCatalog` object

`STACCollection` object

`Item` object

`Items` object

Items functions

Assets functions

Asset preview

Conclusion

Introduction to rstac package

Rolf Simoes, Felipe Carvalho, and Gilberto Camara

2023-01-09

About rstac

Getting started

Creating queries

Making requests

HTTP GET: get_request()

HTTP POST: post_request()

Visualization of the documents

STACCatalog object

STACCollection object

Item object

Items object

Items functions

Assets functions

Asset preview

Conclusion

HTTP GET: `get_request()`

HTTP POST: `post_request()`

`STACCatalog` object

`STACCollection` object

`Item` object

`Items` object