# Getting Started with stacr

    library(stacr)

## Overview

stacr wraps the rstac package with a pipe-friendly, tidy API. Every result is returned as a tibble — never a nested list. The package ships with a catalog registry of known STAC endpoints and supports any STAC API URL.

Key features:

- Tidy output — all functions return tibbles (AD-02)
- Catalog registry — browse Planetary Computer, Earth Search, USGS, and more
- gdalcubes bridge — hand off search results to `gdalcubes` data cubes
- Leaflet mapping — visualize item footprints interactively

## Browse Known Catalogs

`stac_catalogs()` returns a tibble of STAC endpoints bundled with the package:

    stac_catalogs()
    #> # A tibble: 3 × 3
    #>   name               url                                                provider
    #>   <chr>              <chr>                                              <chr>
    #> 1 Earth Search       https://earth-search.aws.element84.com/v1          Element…
    #> 2 Planetary Computer https://planetarycomputer.microsoft.com/api/stac/… Microso…
    #> 3 USGS               https://landsatlook.usgs.gov/stac-server           USGS

## List Collections

Query a STAC API to see what data collections are available:

    stac_collections("https://earth-search.aws.element84.com/v1")
    #> # A tibble: 9 × 3
    #>   id                    title                                        description
    #>   <chr>                 <chr>                                        <chr>
    #> 1 sentinel-2-pre-c1-l2a "Sentinel-2 Pre-Collection 1 Level-2A "      "Sentinel-…
    #> 2 cop-dem-glo-30        "Copernicus DEM GLO-30"                      "The Coper…
    #> 3 naip                  "NAIP: National Agriculture Imagery Program" "The [Nati…
    #> 4 cop-dem-glo-90        "Copernicus DEM GLO-90"                      "The Coper…
    #> 5 landsat-c2-l2         "Landsat Collection 2 Level-2"               "Atmospher…
    #> 6 sentinel-2-l2a        "Sentinel-2 Level-2A"                        "Global Se…
    #> 7 sentinel-2-l1c        "Sentinel-2 Level-1C"                        "Global Se…
    #> 8 sentinel-2-c1-l2a     "Sentinel-2 Collection 1 Level-2A"           "Sentinel-…
    #> 9 sentinel-1-grd        "Sentinel-1 Level-1C Ground Range Detected … "Sentinel-…

## Search for Items

Search for specific items by collection, bounding box, and date range:

    items <- stac_search(
      url = "https://earth-search.aws.element84.com/v1",
      collections = "sentinel-2-l2a",
      bbox = c(-84.5, 38.0, -84.3, 38.2),
      datetime = "2024-06-01T00:00:00Z/2024-06-30T00:00:00Z",
      limit = 5
    )
    items
    #> # A tibble: 5 × 6
    #>   id                       collection     datetime     bbox  geometry     assets
    #>   <chr>                    <chr>          <chr>        <lis> <list>       <list>
    #> 1 S2A_16SGH_20240627_0_L2A sentinel-2-l2a 2024-06-27T… <dbl> <named list> <chr>
    #> 2 S2A_17SKC_20240627_0_L2A sentinel-2-l2a 2024-06-27T… <dbl> <named list> <chr>
    #> 3 S2B_16SGH_20240622_0_L2A sentinel-2-l2a 2024-06-22T… <dbl> <named list> <chr>
    #> 4 S2B_17SKC_20240622_0_L2A sentinel-2-l2a 2024-06-22T… <dbl> <named list> <chr>
    #> 5 S2A_16SGH_20240617_0_L2A sentinel-2-l2a 2024-06-17T… <dbl> <named list> <chr>

Each row is one STAC item with an `id`, `collection`, `datetime`, spatial `bbox` and `geometry`, and a list of available `assets`.

## Browse Items in a Collection

List items directly from a specific collection:

    stac_items(
      url = "https://earth-search.aws.element84.com/v1",
      collection = "sentinel-2-l2a",
      limit = 3
    )
    #> # A tibble: 3 × 6
    #>   id                       collection     datetime     bbox  geometry     assets
    #>   <chr>                    <chr>          <chr>        <lis> <list>       <list>
    #> 1 S2B_22TEQ_20260308_0_L2A sentinel-2-l2a 2026-03-08T… <dbl> <named list> <chr>
    #> 2 S2B_22TFQ_20260308_0_L2A sentinel-2-l2a 2026-03-08T… <dbl> <named list> <chr>
    #> 3 S2B_22TCR_20260308_0_L2A sentinel-2-l2a 2026-03-08T… <dbl> <named list> <chr>

## Bridge to gdalcubes

For raster analysis, use `stac_to_cube()` to hand off items to gdalcubes. This requires the `gdalcubes` package and uses the raw rstac result from `stac_search_raw()`:

    raw <- stac_search_raw(
      url = "https://earth-search.aws.element84.com/v1",
      collections = "sentinel-2-l2a",
      bbox = c(-84.5, 38.0, -84.3, 38.2),
      limit = 10
    )
    cube <- stac_to_cube(raw, asset_names = c("red", "green", "blue"))

## Map Item Footprints

Visualize search results on an interactive leaflet map (requires `leaflet` and `sf`):

    items <- stac_search(
      url = "https://earth-search.aws.element84.com/v1",
      collections = "sentinel-2-l2a",
      bbox = c(-84.5, 38.0, -84.3, 38.2),
      limit = 5
    )
    stac_map(items)