Query a STAC source

A set of helper functions to query STAC APIs. These are very thin wrappers around existing rstac functions, but provide some convenience for common tasks.

Usage

stac_query(
  bbox,
  stac_source,
  collection,
  start_date,
  end_date,
  assets = NULL,
  mpc_sign = grepl("planetarycomputer\\.microsoft\\.com", stac_source),
  drop_duplicates = TRUE,
  check_collection = TRUE
)

sentinel2_stac_query(
  bbox,
  start_date,
  end_date,
  assets = c("B01", "B02", "B03", "B04", "B05", "B06", "B07", "B08", "B8A", "B09", "B11",
    "B12", "SCL"),
  max_cloud_cover = 10,
  stac_source = "https://planetarycomputer.microsoft.com/api/stac/v1/",
  collection = "sentinel-2-l2a"
)

hls_stac_query(
  bbox,
  start_date,
  end_date,
  assets = c("B01", "B02", "B03", "B04", "B05", "B06", "B07", "B08", "B8A", "B09", "B10",
    "B11", "B12", "Fmask"),
  max_cloud_cover = 10,
  stac_source = c("https://planetarycomputer.microsoft.com/api/stac/v1/",
    "https://cmr.earthdata.nasa.gov/stac/LPCLOUD/"),
  collection = c("hls2-s30", "hls2-l30", "HLSS30_2.0", "HLSL30_2.0")
)

sentinel1_stac_query(
  bbox,
  start_date,
  end_date,
  assets = c("hh", "hv", "vh", "vv"),
  orbit_state = c("descending", "ascending"),
  stac_source = "https://planetarycomputer.microsoft.com/api/stac/v1/",
  collection = c("sentinel-1-rtc", "sentinel-1-grd")
)

stac_cloud_filter(items, max_cloud_cover)

stac_orbit_filter(items, orbit_state = c("descending", "ascending"))

stac_coverage_filter(items, bbox, min_coverage = 0.5)

sign_mpc_items(items, subscription_key = Sys.getenv("MPC_TOKEN", unset = NA))

stac_drop_duplicates(items)

Arguments

bbox

A numeric vector of length 4 representing a bounding box

stac_source

The STAC source to query

collection

The collection to query

start_date

The start date for the query

end_date

The end date for the query

assets

A character vector of the asset names to include

mpc_sign

A logical indicating whether to sign the items using the Planetary Computer API's signing method (only required if using the Planetary Computer STAC API).

drop_duplicates

A logical indicating whether to drop duplicate items from the collection. Duplicates are identified based on identical bounding boxes (with a precision of 4 decimal places) and datetime properties. Duplicate items in the Microsoft Planetary Computer STAC API are a known issue.

check_collection

A logical, should the collection name be checked against available collections in the stac_source? If FALSE, the collection is assumed to exist.

max_cloud_cover

A numeric value of the maximum cloud cover percentage

orbit_state

A character string of the orbit state to filter by

items

A rstac doc_items object

min_coverage

A numeric value between 0 and 1 representing the minimum coverage of the bounding box required to retain the item

subscription_key

A subscription key associated with your MPC account. This key will be automatically used if the environment variable MPC_TOKEN is set.

Value

A rstac doc_items object

A STACItemCollection object with signed assets url.

A rstac doc_items object with duplicate items removed

Details

Using these functions to produce a doc_items object is optional; if the user prefers the greater flexibility of using rstac directly, they are encouraged to do so. These functions are only intended to provide a convenient way to interact with STAC APIs.

The Microsoft Planetary Computer (MPC) STAC API is a very convenient, large and open catalogue of EO data. To access these assets, urls must be signed - this can be done using sign_mpc_items, items_sign_planetary_computer, or with GDAL by setting the environment variable VSICURL_PC_URL_SIGNINGtoYES`. see the examples for more details.

sentinel2_stac_query facilitates the querying of the Sentinel-2 level 2A data from the Microsoft Planetary Computer STAC API (or other S2 STAC sources) catalogue to generate a Sentinel 2 rstac doc_items object. This is a convenience function that saves you needing to remember the exact stac source and name but is simply a thin wrapper around stac_query and stac_cloud_filter. Checks are not performed on the stac source or collection name; assets are checked following the collection query and will fail if requested assets are not present in the collection. Note that some STAC sources use different names for the Sentinel-2 level 2A assets and the provided defaults may not work for all sources.

The hls_stac_query function generates a Harmonized Landsat Sentinel (HLS) stac collection doc_items object. In order to access HLS data you will need a NASA Earthdata account. You can create one at https://urs.earthdata.nasa.gov/users/new. Once you have an account, you can set your credentials using the earthdatalogin package as shown in the examples. You can alternatively use the Microsoft Planetary Computer STAC API to access HLS data, which does not require an Earthdata account. Note that you must specify the collection as hls2-s30 or hls2-l30 when using the Planetary Computer STAC API and that the data is only available from 2020 onwards.

The sentinel1_stac_query function generates a Sentinel 1 stac collection doc_items object. It allows you to query Sentinel 1 data from the Planetary Computer STAC API. The function returns a collection of Sentinel 1 items that can be used to generate a Sentinel 1 rstac doc_items object.

The stac_cloud_filter function filters a STAC item collection by cloud cover percentage. It uses the eo:cloud_cover property to filter the items. Items with a cloud cover percentage less than the specified max_cloud_cover are retained.

The stac_orbit_filter function filters a STAC item collection by orbit state. It uses the sat:orbit_state property to filter the items. Items with an orbit state matching the specified orbit_state are retained. It is intended for use with Sentinel-1 data.

The stac_coverage_filter function filters a STAC item collection by minimum coverage of a bounding box. It calculates the area of intersection between the bounding box and the item's bounding box, and retains items where the area of intersection is greater than the specified min_coverage of the bounding box area.

Microsoft no longer provide the ability to generate your own subscription keys. This can be requested depending on the application; see here for further details: https://github.com/microsoft/PlanetaryComputer/issues/457. A key is not required for data access and a more reliable way to ensure access is to collocate the workload on the Azure West Europe region.

Unlike the rstac::items_sign_planetary_computer function, this function caches collection-level signing tokens for 45 minutes to avoid repeated requests for the same collection within a short time period. This can avoid 429 (permission denied) errors when signing many items from the same collection.

The stac_drop_duplicates function removes duplicate items from a STAC item collection. Duplicates are identified based on identical bounding boxes ( with a precision of 4 decimal places), datetime properties and platform. Duplicate items in the Microsoft Planetary Computer STAC API are a known issue.

Examples

if (FALSE) { # interactive()
s2_its <- stac_query(
  bbox = c(-12.386, -37.214, -12.186, -37.014),
  stac_source = "https://planetarycomputer.microsoft.com/api/stac/v1/",
  collection = "sentinel-2-l2a",
  start_date = "2023-01-01",
  end_date = "2023-01-31"
)

# For Microsoft Planetary Computer (MPC) assets, sign the the items using the
# MPC signing `sign_mpc_items()`:
# or use GDAL by setting the following environment variable:
# Sys.setenv("VSICURL_PC_URL_SIGNING" = "YES")
}
if (FALSE) { # interactive()
sentinel2_stac_query(
  bbox = c(-12.386, -37.214, -12.186, -37.014),
  start_date = "2023-01-01",
  end_date = "2023-01-31",
  max_cloud_cover = 10,
  assets = c("B02", "B03", "B04", "B08", "SCL")
)
}
if (FALSE) { # interactive()
hls_query <- hls_stac_query(
  c(144.130, -7.725, 144.470, -7.475),
  start_date = "2023-01-01",
  end_date = "2023-12-31",
  assets = c("B04", "B03", "B02", "Fmask"),
  collection = "HLSS30_2.0",
  max_cloud_cover = 35
)
# in order to download these items (or call further vrt_x functions) you
# will first need to set your credentials. The easiest way to do this is with
# the `earthdatalogin` package. First set your EARTHDATA_USER and
# EARTHDATA_PASSWORD environment variables and then run the following command:

earthdatalogin::edl_netrc(
  username = Sys.getenv("EARTHDATA_USER"),
  password = Sys.getenv("EARTHDATA_PASSWORD")
)
}
if (FALSE) { # interactive()
sentinel1_stac_query(
  bbox = c(-12.386, -37.214, -12.186, -37.014),
  start_date = "2023-01-01",
  end_date = "2023-01-31",
  assets = "vv"
)
}