{"id":26376332,"url":"https://github.com/brazil-data-cube/rstac","last_synced_at":"2025-04-13T06:36:08.830Z","repository":{"id":38451365,"uuid":"274925412","full_name":"brazil-data-cube/rstac","owner":"brazil-data-cube","description":"R Client Library for SpatioTemporal Asset Catalog","archived":false,"fork":false,"pushed_at":"2024-02-14T23:39:36.000Z","size":19710,"stargazers_count":61,"open_issues_count":7,"forks_count":12,"subscribers_count":9,"default_branch":"master","last_synced_at":"2024-03-15T13:47:00.891Z","etag":null,"topics":["geospatial","r","spatiotemporal-asset-catalog","stac"],"latest_commit_sha":null,"homepage":"https://brazil-data-cube.github.io/rstac","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/brazil-data-cube.png","metadata":{"files":{"readme":"README.Rmd","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-06-25T13:37:48.000Z","updated_at":"2024-05-17T15:00:03.507Z","dependencies_parsed_at":"2024-02-18T05:15:17.054Z","dependency_job_id":null,"html_url":"https://github.com/brazil-data-cube/rstac","commit_stats":{"total_commits":803,"total_committers":6,"mean_commits":"133.83333333333334","dds":0.3524283935242839,"last_synced_commit":"8f405baf6d95f70bcf5678c2a2dbe23df4e22b2e"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brazil-data-cube%2Frstac","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brazil-data-cube%2Frstac/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brazil-data-cube%2Frstac/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brazil-data-cube%2Frstac/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brazil-data-cube","download_url":"https://codeload.github.com/brazil-data-cube/rstac/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248675280,"owners_count":21143763,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["geospatial","r","spatiotemporal-asset-catalog","stac"],"created_at":"2025-03-17T03:16:59.325Z","updated_at":"2025-04-13T06:36:08.801Z","avatar_url":"https://github.com/brazil-data-cube.png","language":"R","funding_links":[],"categories":["R"],"sub_categories":[],"readme":"---\noutput: github_document\n---\n\n\u003c!-- README.md is generated from README.Rmd. Please edit that file --\u003e\n\n\n```{r setup, include=FALSE}\nknitr::opts_chunk$set(\n  collapse = TRUE,\n  comment = \"#\u003e\",\n  out.width = \"100%\"\n)\nlibrary(tibble)\n```\n\n# rstac \u003cimg src=\"inst/extdata/img/logo.png\" align=\"right\" width=\"120\"/\u003e\nR Client Library for SpatioTemporal Asset Catalog (rstac)\n\n\n\u003c!-- badges: start --\u003e\n[![Software License](https://img.shields.io/badge/license-MIT-green)](https://github.com/brazil-data-cube/rstac/blob/master/LICENSE)\n\u003c!-- [![Build Status](https://drone.dpi.inpe.br/api/badges/brazil-data-cube/rstac/status.svg)](https://drone.dpi.inpe.br/brazil-data-cube/rstac) --\u003e\n[![R-CMD-check](https://github.com/brazil-data-cube/rstac/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/brazil-data-cube/rstac/actions/workflows/R-CMD-check.yaml)\n[![Build status](https://ci.appveyor.com/api/projects/status/73w7h6u46l1587jj?svg=true)](https://ci.appveyor.com/project/OldLipe/rstac)\n[![codecov](https://codecov.io/gh/brazil-data-cube/rstac/branch/master/graph/badge.svg?token=ILQLPW19UT)](https://app.codecov.io/gh/brazil-data-cube/rstac)\n[![Software Life Cycle](https://img.shields.io/badge/lifecycle-stable-brightgreen.svg)](https://lifecycle.r-lib.org/articles/stages.html)\n[![CRAN status](https://www.r-pkg.org/badges/version/rstac)](https://cran.r-project.org/package=rstac)\n[![STAC API](https://img.shields.io/badge/STAC%20API-v1.0.0-informational)](https://github.com/radiantearth/stac-api-spec)\n[![Join us at Discord](https://img.shields.io/discord/689541907621085198?logo=discord\u0026logoColor=ffffff\u0026color=7389D8)](https://discord.com/channels/689541907621085198#)\n\u003c!-- badges: end --\u003e\n\nSTAC is a specification of files and web services used to describe geospatial \ninformation assets. The specification can be consulted in [https://stacspec.org/](https://stacspec.org/).\n\nR client library for STAC (`rstac`) was designed to fully support STAC API v1.0.0.\nIt also supports earlier versions (\u003e= v0.8.0).\n\n## Installation\n\n```{R install, eval=FALSE}\n# install via CRAN \ninstall.packages(\"rstac\")\n```\n\n### Development version\n\nTo install the development version of `rstac`, run the following commands\n\n```{R install-dev, eval=FALSE}\nremotes::install_github(\"brazil-data-cube/rstac\")\n```\n\nImporting `rstac` package:\n\n```{r load, echo=TRUE, message=FALSE, warning=FALSE}\nlibrary(rstac)\n```\n\n\n## Usage\n\n`rstac` implements the following STAC endpoints:\n\n\n```{R endpoints, echo=FALSE}\n\ntibble::tribble(\n  ~\"**STAC** endpoints\", ~\"`rstac` functions\", ~\"API version\",\n  \"`/`\", \"`stac()`\", \"\u003e= 0.9.0\",\n  \"`/stac`\", \"`stac()`\", \"\u003c 0.9.0\",\n  \"`/collections`\", \"`collections()`\",  \"\u003e= 0.9.0\",\n  \"`/collections/{collectionId}`\", \"`collections(collection_id)`\", \"\u003e= 0.9.0\",\n  \"`/collections/{collectionId}/items`\", \"`items()`\", \"\u003e= 0.9.0\",\n  \"`/collections/{collectionId}/items/{itemId}`\", \"`items(feature_id)`\", \"\u003e= 0.9.0\",\n  \"`/search`\", \"`stac_search()`\", \"\u003e= 0.9.0\",\n  \"`/stac/search`\", \"`stac_search()`\", \"\u003c 0.9.0\",\n  \"`/conformance`\", \"`conformance()`\", \"\u003e= 0.9.0\",\n  \"`/collections/{collectionId}/queryables`\", \"`queryables()`\", \"\u003e= 1.0.0\"\n) %\u003e% as.data.frame() %\u003e% knitr::kable(format = \"markdown\")\n```\n\nThese functions can be used to retrieve information from a STAC API service.\nThe code below creates a `stac` object and list the available collections of \nthe STAC API of the [Brazil Data Cube](http://www.brazildatacube.org/en/home-page-2/) project of \nthe Brazilian National Space Research Institute (INPE).\n\n```{R stac-obj, echo=TRUE}\ns_obj \u003c- stac(\"https://brazildatacube.dpi.inpe.br/stac/\")\n\nget_request(s_obj)\n```\n\nThe variable `s_obj` stores information to connect to the Brazil Data \nCube STAC web service. The `get_request` method makes a HTTP GET connection\nto it and retrieves a STAC Catalog document from the server. Each `links` \nentry is an available collection that can be accessed via STAC API.\n\nIn the code below, we get some STAC items of `CB4-16D-2` collection that\nintersects the bounding box passed to the `bbox` parameter. To do this, we\ncall the `stac_search` function that implements the STAC `/search` \nendpoint. The returned document is a STAC Item Collection (a geojson \ncontaining a feature collection).\n\n```{R bdc-items1, echo=TRUE}\n\nit_obj \u003c- s_obj %\u003e%\n  stac_search(collections = \"CB4-16D-2\",\n              bbox = c(-47.02148, -17.35063, -42.53906, -12.98314),\n              limit = 100) %\u003e% \n  get_request()\n\nit_obj\n```\n\nThe `rstac` uses the [httr](https://github.com/r-lib/httr) package to manage \nHTTP requests, allowing the use of tokens from the authorization protocols OAuth\n1.0 or 2.0 as well as other configuration options. In the code below, we present\nan example of how to pass a parameter token on a HTTP request.\n\n```{R bdc-items2, eval=FALSE}\nit_obj \u003c- s_obj %\u003e%\n  stac_search(collections = \"CB4-16D-2\",\n              bbox = c(-47.02148, -17.35063, -42.53906, -12.98314)) %\u003e%\n  get_request(add_headers(\"x-api-key\" = \"MY-TOKEN\"))\n```\n\nIn addition to the functions mentioned above, the `rstac` package provides some \nextra functions for handling items and to bulk download the assets.\n\n### Items functions\n\n`rstac` provides some functions that facilitates the interaction with STAC data.\nIn the example below, we get how many items matched the search criteria:\n\n```{R bdc-items3, echo=TRUE}\n# it_obj variable from the last code example\nit_obj %\u003e% \n  items_matched()\n```\n\nHowever, if we count how many items there are in `it_obj` variable, we get `10`,\nmeaning that more items could be fetched from the STAC service:\n\n```{R bdc-items4, echo=TRUE}\nit_obj %\u003e% \n  items_length()\n```\n\n\n```{R bdc-items5, echo=TRUE}\n# fetch all items from server \n# (but don't stored them back in it_obj)\nit_obj \u003c- it_obj %\u003e% \n  items_fetch(progress = FALSE) \n\nit_obj %\u003e%\n  items_length()\n```\n\n### Download assets\n\nAll we've got in previous example was metadata to STAC Items, including\nlinks to geospatial data called `assets`. To download all `assets` in a\nSTAC Item Collection we can use `assets_download()` function, that returns\nan update STAC Item Collection referring to the downloaded assets. The code\nbelow downloads the `thumbnail` assets (.png files) of `10` items stored in\n`it_obj` variable.\n\n```{R download, eval=FALSE}\ndownload_items \u003c- it_obj %\u003e%\n  assets_download(assets_name = \"thumbnail\", items_max = 10)\n```\n\n### CQL2 query filter\n\n`rstac` also supports advanced query filter using common query language (CQL2).\nUsers can write complex filter expressions using R code in an easy and \nnatural way. For a complete \n\n```{R cql2, echo=TRUE}\ns_obj \u003c- stac(\"https://planetarycomputer.microsoft.com/api/stac/v1\")\n\nit_obj \u003c- s_obj %\u003e% \n  ext_filter(\n    collection == \"sentinel-2-l2a\" \u0026\u0026 `s2:vegetation_percentage` \u003e= 50 \u0026\u0026\n      `eo:cloud_cover` \u003c= 10 \u0026\u0026 `s2:mgrs_tile` == \"20LKP\" \u0026\u0026 \n      anyinteracts(datetime, interval(\"2020-06-01\", \"2020-09-30\"))\n  ) %\u003e%\n  post_request()\n```\n\n## Getting help\n\nYou can get a full explanation about each STAC (v1.0.0) endpoint at [STAC API spec](https://github.com/radiantearth/stac-api-spec/tree/master/ogcapi-features). A detailed\ndocumentation with examples on how to use each endpoint and other functions\navailable in the `rstac` package can be obtained by typing `?rstac` in R \nconsole.\n\n## Citation\n\nTo cite rstac in publications use:\n\nR. Simoes, F. C. de Souza, M. Zaglia, G. R. de Queiroz, R. D. C. dos Santos\nand K. R. Ferreira, \"Rstac: An R Package to Access Spatiotemporal Asset\nCatalog Satellite Imagery,\" 2021 IEEE International Geoscience and Remote\nSensing Symposium IGARSS, 2021, pp. 7674-7677, doi:\n10.1109/IGARSS47720.2021.9553518.\n\n## Acknowledgements for financial support\n\nWe acknowledge and thank the project funders that provided financial and material support:\n\n- 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.\n\n- Radiant Earth Foundation and STAC Project Steering Committee for the advance of STAC ecosystem programme.\n\n- 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)\n\n## How to contribute?\n\nThe `rstac` package was implemented based on an extensible architecture, so \nfeel free to contribute by implementing new STAC API \n[extensions/fragments](https://github.com/radiantearth/stac-api-spec/tree/master/fragments) \nbased on the STAC API specifications.\n\n1. Make a project\n[fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo).\n2. Create a file inside the `R/` directory called `ext_{extension_name}.R`.\n3. In the code, you need to specify a subclass name (e.g.`my_subclass`) for \nyour extension and use it when calling [`rstac_query()`](https://github.com/brazil-data-cube/rstac/blob/master/R/query-funs.R) function. You also need to implement for your subclass the following S3 generic functions: [`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 generics methods you \ncan define how parameters should be submitted to the HTTP request and the types \nof the returned documents. See the implemented [ext_filter](https://github.com/brazil-data-cube/rstac/blob/master/R/ext_filter.R) \nAPI extension as an example.\n4. Make a [Pull Request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request) on the most recent [development branch](https://github.com/brazil-data-cube/rstac/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrazil-data-cube%2Frstac","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrazil-data-cube%2Frstac","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrazil-data-cube%2Frstac/lists"}