Type: Package
Title: Search Download and Handle Data from Copernicus Marine Service Information
Version: 0.2.6
Author: Pepijn de Vries ORCID iD [aut, cre, dtc]
Maintainer: Pepijn de Vries <pepijn.devries@outlook.com>
Description: Subset and download data from EU Copernicus Marine Service Information: https://data.marine.copernicus.eu. Import data on the oceans physical and biogeochemical state from Copernicus into R without the need of external software.
Depends: R (≥ 4.1.0)
Imports: aws.s3, cli, dplyr, httr2, leaflet, purrr, rlang, sf, stringr, tibble, tidyr, xml2
Suggests: lifecycle, ncmeta, stars, testthat (≥ 3.0.0)
URL: https://github.com/pepijn-devries/CopernicusMarine, https://pepijn-devries.github.io/CopernicusMarine/
BugReports: https://github.com/pepijn-devries/CopernicusMarine/issues
License: GPL (≥ 3)
Encoding: UTF-8
RoxygenNote: 7.3.2
Config/testthat/edition: 3
Collate: 'CopernicusMarine-package.r' 'cms_catalogue_entry.R' 'cms_cite_product.r' 'cms_download_native.R' 'cms_download_stac.r' 'cms_login.r' 'cms_download_subset.r' 'cms_list_stac_files.r' 'cms_product_details.r' 'cms_product_metadata.r' 'cms_product_services.r' 'cms_products_list.r' 'cms_stac_properties.r' 'generics.r' 'cms_wmts.r' 'import.r'
NeedsCompilation: no
Packaged: 2025-07-14 08:20:17 UTC; vries171
Repository: CRAN
Date/Publication: 2025-07-14 12:30:10 UTC

CopernicusMarine: Search Download and Handle Data from Copernicus Marine Service Information

Description

logo

Subset and download data from EU Copernicus Marine Service Information: https://data.marine.copernicus.eu. Import data on the oceans physical and biogeochemical state from Copernicus into R without the need of external software.

Author(s)

Maintainer: Pepijn de Vries pepijn.devries@outlook.com (ORCID) [data contributor]

See Also

Useful links:

How to cite a Copernicus marine product

Description

[Stable] Get details for properly citing a Copernicus product.

Usage

cms_cite_product(product)

Arguments

product

An identifier (type character) of the desired Copernicus marine product. Can be obtained with cms_products_list.

Value

Returns a vector of character strings. The first element is always the product title, id and doi. Remaining elements are other associated references. Note that the remaining references are returned as listed at Copernicus. Note that the citing formatting does not appear to be standardised.

Author(s)

Pepijn de Vries

See Also

Other product-functions: cms_product_details(), cms_product_services(), cms_products_list()

Examples

cms_cite_product("SST_MED_PHY_SUBSKIN_L4_NRT_010_036")

Download raw files as provided to Copernicus Marine

Description

[Experimental] Full marine data sets can be downloaded using the functions documented here. Use cms_list_native_files() to list available files, and cms_download_native() to download specific files. Files are usually organised per product, layer, year, month and day.

Usage

cms_download_native(destination, product, layer, pattern, progress = TRUE, ...)

cms_list_native_files(product, layer, pattern, ...)

Arguments

destination

Path where to store the downloaded file(s).

product

An identifier (type character) of the desired Copernicus marine product. Can be obtained with cms_products_list.

layer

The name of a desired layer within a product (type character). Can be obtained with cms_product_details.

pattern

A regular expression (regex) pattern. Only paths that match the pattern will be returned. It can be used to select specific files. For instance if pattern = "2022/06/", only files for the year 2022 and the month June will be listed (assuming that the file path is structured as such, see examples)

progress

A logical value. When TRUE a progress bar is shown.

...

Ignored

Value

Returns NULL invisibly.

Author(s)

Pepijn de Vries

Examples

if (interactive()) {
  cms_list_native_files(
    product       = "GLOBAL_ANALYSISFORECAST_PHY_001_024",
    layer         = "cmems_mod_glo_phy_anfc_0.083deg_PT1H-m",
    pattern       = "2022/06/"
  )

## Use 'pattern' to download a file for a specific day:
  cms_download_native(
    destination   = tempdir(),
    product       = "GLOBAL_ANALYSISFORECAST_PHY_001_024",
    layer         = "cmems_mod_glo_phy_anfc_0.083deg_PT1H-m",
    pattern       = "m_20220630"
  )
}

Deprecated

Description

[Deprecated] Full marine data sets can be downloaded using the SpatioTemporal Asset Catalogs (STAC). The API for interacting with these files is no longer operational. Please use cms_download_native() instead.

Usage

cms_download_stac(
  file_tibble,
  destination,
  show_progress = TRUE,
  overwrite = FALSE
)

cms_list_stac_files(product, layer)

cms_stac_properties(product, layer)

Arguments

file_tibble

Ignored

destination

Ignored

show_progress

Ignored

overwrite

A logical value. When FALSE (default), files at the destination won't be overwritten when the exist. Instead an error will be thrown if this is the case. When set to TRUE, existing files will be overwritten.

product

An identifier (type character) of the desired Copernicus marine product. Can be obtained with cms_products_list.

layer

The name of a desired layer within a product (type character). Can be obtained with cms_product_details.

Value

returns NULL, as the API is no longer available

Author(s)

Pepijn de Vries

Subset and download a specific marine product from Copernicus

Description

[Questioning] Subset and download a specific marine product from Copernicus. You need to register an account at https://data.marine.copernicus.eu before you can use this function.

Usage

cms_download_subset(
  username = cms_get_username(),
  password = cms_get_password(),
  destination,
  product,
  layer,
  variable,
  region,
  timerange,
  verticalrange,
  overwrite = FALSE
)

Arguments

username

Your Copernicus marine user name. Can be provided with cms_get_username() (default), or as argument here.

password

Your Copernicus marine password. Can be provided as cms_get_password() (default), or as argument here.

destination

File or path where the requested file will be downloaded to.

product

An identifier (type character) of the desired Copernicus marine product. Can be obtained with cms_products_list.

layer

The name of a desired layer within a product (type character). Can be obtained with cms_product_details.

variable

The name of a desired variable in a specific layer of a product (type character). Can be obtained with cms_product_details.

region

Specification of the bounding box as a vector of numerics WGS84 lat and lon coordinates. Should be in the order of: xmin, ymin, xmax, ymax.

timerange

A vector with two elements (lower and upper value) for a requested time range. The vector should be coercible to POSIXct.

verticalrange

A vector with two elements (minimum and maximum) numerical values for the depth of the vertical layers (if any). Note that values below the sea surface needs to be specified as negative values.

overwrite

A logical value. When FALSE (default), files at the destination won't be overwritten when the exist. Instead an error will be thrown if this is the case. When set to TRUE, existing files will be overwritten.

Value

Returns a logical value invisibly indicating whether the requested file was successfully stored at the destination.

Author(s)

Pepijn de Vries

Examples

## Not run: 
destination <- tempfile("copernicus", fileext = ".nc")

## Assuming that Copernicus account details are provided as `options`
cms_download_subset(
  destination   = destination,
  product       = "GLOBAL_ANALYSISFORECAST_PHY_001_024",
  layer         = "cmems_mod_glo_phy-cur_anfc_0.083deg_P1D-m",
  variable      = "sea_water_velocity",
  region        = c(-1, 50, 10, 55),
  timerange     = c("2021-01-01 UTC", "2021-01-02 UTC"),
  verticalrange = c(0, -2)
)

mydata <- stars::read_stars(destination)

plot(mydata["vo"])

## End(Not run)

Get information about Copernicus Marine clients

Description

This function retrieves the client information from the Copernicus Marine Service. Among others, it lists where to find the catalogues required by this package

Usage

cms_get_client_info(...)

Arguments

...

Ignored

Value

In case of success it returns a named list with information about the available Copernicus Marine clients.

Author(s)

Pepijn de Vries

Examples

if (interactive()) {
  cms_get_client_info()
}

Set or get Copernicus account details

Description

Set or get username and password throughout an R session. This can be used to obscure your account details in an R script and store them as either an R option or system environment variable.

Usage

cms_get_username()

cms_get_password()

cms_set_username(username, method = c("option", "sysenv"))

cms_set_password(password, method = c("option", "sysenv"))

Arguments

username

Your Copernicus Marine username

method

Either "option" to use R options to store account details. Use "sysenv" to store account details as system environment variable.

password

Your Copernicus Marine password

Value

Returns your account details for the get variant or nothing in case of the set variant.

Author(s)

Pepijn de Vries

Examples

if (interactive()) {
  ## Returns your account details only if they have been set for your session
  cms_get_username()
  cms_get_password()
}

Contact Copernicus Marine login page

Description

[Stable] Contact Copernicus Marine login page and check if login is successful.

Usage

cms_login(username = cms_get_username(), password = cms_get_password())

Arguments

username

Your Copernicus marine user name. Can be provided with cms_get_username() (default), or as argument here.

password

Your Copernicus marine password. Can be provided as cms_get_password() (default), or as argument here.

Details

This function will return your account details if successful.

Value

Returns a named list with your account details if successful, returns NULL otherwise.

Author(s)

Pepijn de Vries

Examples

if (interactive()) {
  cms_login()
}

Obtain details for a specific Copernicus marine product

Description

[Experimental] Obtain details for a specific Copernicus marine product.

Usage

cms_product_details(product, layer, variant, ...)

Arguments

product

An identifier (type character) of the desired Copernicus marine product. Can be obtained with cms_products_list.

layer

[Deprecated] Ignored and deprecated

variant

[Deprecated] Ignored and deprecated

...

Ignored

Value

Returns a named list with product details.

Author(s)

Pepijn de Vries

See Also

Other product-functions: cms_cite_product(), cms_product_services(), cms_products_list()

Examples

if (interactive()) {
  cms_product_details("GLOBAL_ANALYSISFORECAST_PHY_001_024")
}

Obtain product meta data

Description

[Experimental] Obtain product meta data such as spatio-temporal bounds of the data.

Usage

cms_product_metadata(product, type, ...)

Arguments

product

An identifier (type character) of the desired Copernicus marine product. Can be obtained with cms_products_list.

type

[Deprecated] Deprecated and ignored.

...

Ignored

Value

Returns a data.frame/tibble with the metadata. Each row in the data.frame represents a layer available for the product.

Author(s)

Pepijn de Vries

Examples

if (interactive()) {
  cms_product_metadata("GLOBAL_ANALYSISFORECAST_PHY_001_024")
}

Obtain available services for a specific Copernicus marine product

Description

[Experimental] Obtain an overview of services provided by Copernicus for a specific marine product.

Usage

cms_product_services(product, ...)

Arguments

product

An identifier (type character) of the desired Copernicus marine product. Can be obtained with cms_products_list.

...

Ignored.

Value

Returns a tibble with a list of available services for a Copernicus marine product.

Author(s)

Pepijn de Vries

See Also

Other product-functions: cms_cite_product(), cms_product_details(), cms_products_list()

Examples

if (interactive()) {
  cms_product_services("GLOBAL_ANALYSISFORECAST_PHY_001_024")
}

List products available from data.marine.copernicus.eu

Description

[Stable] Collect a list of products and some brief descriptions for marine products available from Copernicus. cms_products_list() does not use a formal API, but provides a more detailed list. cms_products_list2() Does use the formal API, but provides less details

Usage

cms_products_list(..., info_type = c("list", "meta"))

cms_products_list2(...)

Arguments

...

Allows you to pass (search) query parameters to apply to the list. When omitted, the full list of products is returned.

info_type

One of "list" (default) or "meta". "list" returns the actual list whereas "meta" returns meta information for the executed query (e.g. number of hits).

Value

Returns a tibble of products available from https://data.marine.copernicus.eu or a named list when info_type = "meta". Returns NULL in case on-line services are unavailable.

Author(s)

Pepijn de Vries

See Also

Other product-functions: cms_cite_product(), cms_product_details(), cms_product_services()

Examples

cms_products_list()

## Query a specific product:
cms_products_list(freeText = "GLOBAL_ANALYSISFORECAST_PHY_001_024")

Obtain a WMTS entry for specific Copernicus marine products and add to a leaflet map

Description

[Stable] Functions for retrieving Web Map Tile Services information for specific products, layers and variables and add them to a leaflet map.

Usage

cms_wmts_details(product, layer, variable)

addCmsWMTSTiles(
  map,
  product,
  layer,
  variable,
  tilematrixset = "EPSG:3857",
  options = leaflet::WMSTileOptions(format = "image/png", transparent = TRUE),
  ...
)

cms_wmts_get_capabilities(product, layer, variable, type = c("list", "xml"))

Arguments

product

An identifier (type character) of the desired Copernicus marine product. Can be obtained with cms_products_list.

layer

The name of a desired layer within a product (type character). Can be obtained with cms_product_details.

variable

The name of a desired variable in a specific layer of a product (type character). Can be obtained with cms_product_details.

map

A map widget object created from leaflet::leaflet()

tilematrixset

A character string representing the tilematrixset to be used. In many cases "EPSG:3857" (Pseudo-Mercator) or "EPSG:4326" (World Geodetic System 1984) are available, but should be checked with cms_wmts_details.

options

Passed on to leaflet::addWMSTiles().

...

Passed on to leaflet::addWMSTiles().

type

A character string indicating whether the capabilities should be returned as "list" (default) or "xml" (xml2::xml_new_document()).

Value

cms_wmts_details returns a tibble with detains on the WMTS service. cms_wmts_getcapabilities returns either a list or xml_document depending on the value of type. AddCmsWMTSTiles returns a leaflet map updated with the requested tiles.

Author(s)

Pepijn de Vries

Examples

wmts_details <-
  cms_wmts_details(
    product  = "GLOBAL_ANALYSISFORECAST_PHY_001_024",
    layer    = "cmems_mod_glo_phy-thetao_anfc_0.083deg_P1D-m",
    variable = "thetao"
  )

cms_wmts_get_capabilities("GLOBAL_ANALYSISFORECAST_PHY_001_024")

if (interactive() && nrow(wmts_details) > 0) {
  leaflet::leaflet() |>
    leaflet::setView(lng = 3, lat = 54, zoom = 4) |>
    leaflet::addProviderTiles("Esri.WorldImagery") |>
    addCmsWMTSTiles(
      product  = "GLOBAL_ANALYSISFORECAST_PHY_001_024",
      layer    = "cmems_mod_glo_phy-thetao_anfc_0.083deg_P1D-m",
      variable = "thetao")
}