Find CMR collections by keyword, short name, or provider

Thin wrapper around CMR's collection search (https://cmr.earthdata.nasa.gov/search/collections.umm_json), useful for discovering a short_name to pass to cmr_audit_revisions() or cmr_find_granules(), or for a quick keyword search across all collections (title, abstract, science keywords, platforms, instruments, ...).

Usage

cmr_find_collections(
  keyword = NULL,
  short_name = NULL,
  provider = NULL,
  page_size = 100,
  page_num = 1,
  granule_count = TRUE
)

Arguments

keyword

Free-text search term(s), e.g. "sea surface temperature". Matched by CMR against title, abstract, and other collection metadata fields – not an exact match.

short_name

Exact (or CMR-wildcarded, with options[short_name][pattern]=true handled separately – not exposed here) collection short name.

provider

Optional CMR provider id (e.g. "POCLOUD", "LAADS") to restrict the search.

page_size

Max collections to return per request (CMR hard limit 2000).

page_num

Which page of results to fetch (1-based). Mainly useful via cmr_all_collections(), which pages through this automatically – most interactive callers can leave this at the default.

granule_count

Fetch each collection's live granule count (via a second request to collections.json?include_granule_counts=true – collections.umm_json has no such field). Default TRUE. This is the most direct way to spot a collection with no UMM-G granules at all (granule_count == 0) – some collections (a few AADC ones among them) register a single static download at the collection level with nothing underneath, so cmr_find_granules() will correctly return nothing for them. Set FALSE to skip the extra request if you don't need it.

Value

A tibble::tibble() with one row per collection: short_name, entry_title, concept_id, provider, version, processing_level, abstract, region, s3_credentials_endpoint. region is the AWS region (e.g. "us-west-2") a cloud-hosted collection's data lives in – s3_urls from cmr_find_granules() are only cheaply/directly readable from compute in that region; from elsewhere you're reading over the public internet (egress charges, no speed benefit), and some buckets block it outright. Both columns are NA for collections with no direct S3 distribution (only an https mirror). s3_credentials_endpoint is required regardless of region: s3_urls aren't publicly readable – you exchange an Earthdata Login token there for temporary AWS credentials. temporal_start/temporal_end are the collection's declared available date range (UMM-C TemporalExtents) – this is provider-entered metadata, not derived from a live granule search, so treat it as a stated range rather than a guarantee; for collections with no UMM-G granules at all (a single static download registered only at the collection level – some AADC collections are like this) it's the only date range CMR has. temporal_end is NA when ends_at_present is TRUE (an actively-growing collection; any recorded end date would go stale the moment a new granule lands). Be aware ends_at_present itself is frequently left FALSE (unset) on collections that are, in fact, still actively growing – a spot-check of 6 GHRSST-family collections found only 1 correctly declared TRUE; the other 5 all had granules in the last 14 days despite FALSE. Treat FALSE as "unset/unknown" rather than "this collection has stopped" – check recent granules directly (cmr_find_granules()) if liveness matters. If more collections match than page_size allows, a message reports the total hit count – raise page_size (or narrow keyword/provider) to see more, or use cmr_all_collections() to page through everything. At least one of keyword or short_name must be supplied (pass keyword = "" to match every collection, as in cmr_all_collections()'s default). The total hit count is also attached as the "hits" attribute, for programmatic pagination.

See also

Other collection functions: cmr_all_collections(), cmr_collection_liveness()

Examples

# \donttest{
cmr_find_collections(keyword = "sea surface temperature", provider = "POCLOUD")
#> 100 of 499 total matching collections returned (page 1) -- raise `page_size` (CMR max 2000), narrow `keyword`/`provider`, or use cmr_all_collections() to see more.
#> # A tibble: 100 × 13
#>    short_name  entry_title concept_id provider version processing_level abstract
#>    <chr>       <chr>       <chr>      <chr>    <chr>   <chr>            <chr>   
#>  1 OSTIA-UKMO… GHRSST Lev… C25867862… POCLOUD  2.0     4                "The Op…
#>  2 MUR-JPL-L4… GHRSST Lev… C19968811… POCLOUD  4.1     4                "A Grou…
#>  3 MUR25-JPL-… GHRSST Lev… C20368806… POCLOUD  4.2     4                "A Grou…
#>  4 MODIS_T-JP… GHRSST Lev… C19404755… POCLOUD  2019.0  2                "NASA p…
#>  5 OSTIA-UKMO… GHRSST Lev… C20368775… POCLOUD  2.0     4                "A Grou…
#>  6 H09-AHI-L3… GHRSST L3C… C27448097… POCLOUD  2.90    3                "The H0…
#>  7 AVHRR_OI-N… GHRSST Lev… C20368817… POCLOUD  2.1     4                "A Grou…
#>  8 CMC0.1deg-… GHRSST Lev… C20368817… POCLOUD  3.0     4                "A Grou…
#>  9 G18-ABI-L3… GHRSST L3C… C27310413… POCLOUD  2.90    3                "The G1…
#> 10 AMSR2-REMS… GHRSST Lev… C25969834… POCLOUD  8.2     2P               "This p…
#> # ℹ 90 more rows
#> # ℹ 6 more variables: region <chr>, s3_credentials_endpoint <chr>,
#> #   temporal_start <chr>, temporal_end <chr>, ends_at_present <lgl>,
#> #   granule_count <int>
cmr_find_collections(short_name = "MUR-JPL-L4-GLOB-v4.1")
#> # A tibble: 1 × 13
#>   short_name   entry_title concept_id provider version processing_level abstract
#>   <chr>        <chr>       <chr>      <chr>    <chr>   <chr>            <chr>   
#> 1 MUR-JPL-L4-… GHRSST Lev… C19968811… POCLOUD  4.1     4                "A Grou…
#> # ℹ 6 more variables: region <chr>, s3_credentials_endpoint <chr>,
#> #   temporal_start <chr>, temporal_end <chr>, ends_at_present <lgl>,
#> #   granule_count <int>
# }