Title:	Search Download and Handle Data from Copernicus Climate Data Service
Version:	0.0.3
Description:	Subset and download data from EU Copernicus Climate Data Service: https://cds.climate.copernicus.eu/. Import information about the Earth's past, present and future climate from Copernicus into R without the need of external software.
Depends:	R (≥ 4.1.0)
Imports:	dplyr, httr2, jsonlite, methods, purrr, rlang, stringr, tibble, tidyr
Suggests:	clipr, ggplot2, knitr, RefManageR, rmarkdown, stars, testthat (≥ 3.0.0)
License:	GPL (≥ 3)
Encoding:	UTF-8
RoxygenNote:	7.3.2
Collate:	'CopernicusClimate-package.R' 'helpers.R' 'catalogue.R' 'cite.R' 'jobs.R' 'licenses.R' 'python.R' 'retrieve.R' 'stars.R' 'token.R'
Config/testthat/edition:	3
URL:	https://pepijn-devries.github.io/CopernicusClimate/, https://github.com/pepijn-devries/CopernicusClimate/
BugReports:	https://github.com/pepijn-devries/CopernicusMarine/issues
VignetteBuilder:	knitr
NeedsCompilation:	no
Packaged:	2025-10-23 07:22:48 UTC; vries171
Author:	Pepijn de Vries [aut, cre]
Maintainer:	Pepijn de Vries <pepijn.devries@outlook.com>
Repository:	CRAN
Date/Publication:	2025-10-23 10:40:35 UTC

CopernicusClimate: Search Download and Handle Data from Copernicus Climate Data Service

Description

Subset and download data from EU Copernicus Climate Data Service: https://cds.climate.copernicus.eu/. Import information about the Earth's past, present and future climate from Copernicus into R without the need of external software.

Author(s)

Maintainer: Pepijn de Vries pepijn.devries@outlook.com (ORCID)

See Also

Useful links:

• https://pepijn-devries.github.io/CopernicusClimate/

• https://github.com/pepijn-devries/CopernicusClimate/

• Report bugs at https://github.com/pepijn-devries/CopernicusMarine/issues

Accept a specific licence

Description

Call this function if you wish to accept a specific license.

Usage

cds_accept_licence(license, revision, ..., token = cds_get_token())

Arguments

Value

Returns a data.frame containing the accepted license

See Also

Other licences: cds_accepted_licences(), cds_list_licences()

Examples

if (interactive() && cds_token_works()) {
  cds_accept_licence("cc-by", 1)
}

List accepted licences

Description

In order to use specific features of the Climate Data Service, you may first need to accept specific licences. This function will list all licenses you have accepted.

Usage

cds_accepted_licences(
  scope = c("all", "dataset", "portal"),
  ...,
  token = cds_get_token()
)

Arguments

Value

Returns a data.frame listing the accepted licenses.

See Also

Other licences: cds_accept_licence(), cds_list_licences()

Examples

if (interactive() && cds_token_works()) {
  cds_accepted_licences("portal")
}

Get Prometheus metrics for account

Description

Obtain account metrics that can be interpreted with prometheus

Usage

cds_account_metrics(token = cds_get_token(), ...)

Arguments

Value

Returns text that can be interpreted with prometheus

Examples

if (interactive() && cds_token_works()) {
  cds_account_metrics()
}

Prepare a request for downloading a dataset

Description

This function is used by cds_estimate_costs() and cds_submit_job() to subset a dataset before downloading. It will also help you to explore which parameters are available for subsetting.

Usage

cds_build_request(dataset, ...)

Arguments

Value

Returns a named list, which can be used to submit a job (cds_submit_job()) or inquiry its cost (cds_estimate_costs()).

Examples

if (interactive()) {
  cds_build_request(
    dataset        = "reanalysis-era5-pressure-levels",
    variable       = "geopotential",
    product_type   = "reanalysis",
    area           = c(n = 55, w = -1, s = 50, e = 10),
    year           = "2024",
    month          = "03",
    day            = "01",
    pressure_level = "1000",
    data_format    = "netcdf"
  )
}

List catalogue vocabulary

Description

The catalogue uses a specific vocabulary for keywords. This function produces an overview.

Usage

cds_catalogue_vocabulary(...)

Arguments

Value

Returns a data.frame of keyword vocabulary used by the catalogue.

Examples

if (interactive()) {
  cds_catalogue_vocabulary()
}

Check if authentication works with a specific token

Description

Checks if the specified API key can be used for authentication at the Climate Data Service.

Usage

cds_check_authentication(token = cds_get_token(), ...)

cds_token_works(token = cds_get_token(), ...)

Arguments

Value

cds_check_authentication() will return some account information when successful but throws an error if it is not. In contrast cds_token_works() returns a logical value and will not throw an error upon failure.

Examples

if (interactive() && cds_token_works()) {
  cds_check_authentication()
}

Cite a dataset

Description

Use this function to obtain citation details for a specific dataset

Usage

cds_cite_dataset(dataset, ...)

Arguments

Value

Returns a BibEntry-class object, with citation details for the requested dataset

Examples

if (interactive()) {
  cds_cite_dataset("reanalysis-era5-pressure-levels")
}

Obtain an overview of options to subset a dataset

Description

This function provides an overview of parameters that can be used to subset a dataset. It can help you set up a request with cds_submit_job() or cds_build_request().

Usage

cds_dataset_form(dataset, ...)

Arguments

Value

A data.frame with aspects of the dataset that can be subsetted, when defining a job. See also cds_submit_job() and cds_build_request()

Examples

if (interactive() && cds_token_works()) {
  cds_dataset_form("reanalysis-era5-pressure-levels")
}

Delete/cancel jobs submitted to the Climate Data Service

Description

Whe you regret submitting a job, you can cancel it by calling this function.

Usage

cds_delete_job(job_id, ..., token = cds_get_token())

Arguments

Value

Returns a data.frame with information about the cancelled job.

Examples

if (interactive() && cds_token_works()) {
  job <- cds_submit_job(
      dataset        = "reanalysis-era5-pressure-levels",
      variable       = "geopotential",
      product_type   = "reanalysis",
      area           = c(n = 55, w = -1, s = 50, e = 10),
      year           = "2024",
      month          = "03",
      day            = "01",
      pressure_level = "1000",
      data_format    = "netcdf"
    )
  cds_delete_job(job$jobID, tempdir())
}

Download specific jobs

Description

After submitting one or more jobs with cds_submit_job(), you can download the resulting files with cds_download_jobs(). See vignette("download") for more details.

Usage

cds_download_jobs(job_id, destination, names, ..., token = cds_get_token())

Arguments

Value

A data.frame of all downloaded files. Contains a column local with the path to the locally stored files.

Examples

if (interactive() && cds_token_works()) {
  job <- cds_submit_job(
      dataset        = "reanalysis-era5-pressure-levels",
      variable       = "geopotential",
      product_type   = "reanalysis",
      area           = c(n = 55, w = -1, s = 50, e = 10),
      year           = "2024",
      month          = "03",
      day            = "01",
      pressure_level = "1000",
      data_format    = "netcdf"
    )
  cds_download_jobs(job$jobID, tempdir())
}

Check the cost of a request against your quota

Description

Each account has a limit to the amount of data that can be downloaded. Use this function to check if a request exceeds your quota.

Usage

cds_estimate_costs(dataset, ..., token = cds_get_token())

Arguments

Value

Returns a named list indicating the available quota and the estimated cost for a request specified with ...-arguments.

Examples

if (interactive() && cds_token_works()) {
  cds_estimate_costs(
    dataset        = "reanalysis-era5-pressure-levels",
    variable       = "geopotential",
    product_type   = "reanalysis",
    area           = c(n = 55, w = -1, s = 50, e = 10),
    year           = "2024",
    month          = "03",
    day            = "01",
    pressure_level = "1000",
    data_format    = "netcdf"
  )
  
  cds_estimate_costs(dataset = "reanalysis-era5-pressure-levels")
}

Get account details

Description

Retrieve account details associated with the provided token

Usage

cds_get_account(token = cds_get_token(), ...)

Arguments

Value

Returns a named list with account details.

Examples

if (interactive() && cds_token_works()) {
  cds_get_account()
}

Get or set a Climate Data Service API key

Description

Many of the Climate Data Services features require a personal Application Programming Interface (API) key. This function will get a token that was previously stored (cds_set_token()), and can be used throughout the R session.

Usage

cds_get_token(...)

cds_set_token(token, method = c("option", "sysenv"), ...)

Arguments

Details

To use an API key, you first need to get one from the Climate Data Service. You can do so, by creating an account and then initialise the key at https://cds.climate.copernicus.eu/profile.

There are different locations where the key can be stored and where cds_get_token() will look. It will look for the first successful value of (in order): the environment variable named "CDSAPI_KEY", the R getOption() named "CDSAPI_KEY", the environment variable named "ECMWF_DATASTORES_KEY", and the R getOption() named "ECMWF_DATASTORES_KEY".

You can set the key at the start of each R session with cds_set_token(). If you want a persistent solution, you can add the environment variable (with names shown above) to your system. Or you can add the option (with the names shown above) to your ".profile" file. This will help you obscure your sensitive account information in your R script.

Value

cds_get_token() will return an API key token if it has been set. If it is not set it will return an empty string: "". cds_set_token() will return NULL invisibly.

Examples

if (interactive() && !cds_token_works()) {
  cds_set_token("this-is-a-dummy-token", "option")
}

if (interactive()) {
  cds_get_token()
}

List or search Climate Data Service datasets

Description

This will help you decide which datasets you wish to obtain.

Usage

cds_list_datasets(dataset, ...)

cds_search_datasets(search, keywords, page = 0, limit = 50, ...)

Arguments

Value

A data.frame listing the datasets from the Climate Data Service. In case of cds_search_datasets(), attributes named SearchMeta are added containing the number of matching and number of returned datasets.

Examples

if (interactive()) {
  cds_list_datasets()
  cds_search_datasets("rain", "Temporal coverage: Future")
}

List jobs submitted to the Climate Data Service

Description

Once submitted with cds_submit_job() you can check the status of the job with this function. You can list all available jobs, or specific jobs.

Usage

cds_list_jobs(
  job_id = NULL,
  status = NULL,
  limit = 50,
  ...,
  token = cds_get_token()
)

Arguments

Value

Returns a data.frame of submitted jobs.

Examples

if (interactive() && cds_token_works()) {
  cds_list_jobs()
}

Obtain a list of licences that can be accepted

Description

Some datasets require you to accept specific licences. This function will provide an overview of all licences associated with datasets and can be accepted.

Usage

cds_list_licences(...)

Arguments

Value

Returns a data.frame of available licences that can be accepted.

See Also

Other licences: cds_accept_licence(), cds_accepted_licences()

Examples

if (interactive()) {
  cds_list_licences()
}

Translate Python Climate Data Store request to R request

Description

When looking for a dataset on https://cds.climate.copernicus.eu/datasets, you have the option to copy the API request code to the clipboard. However, this is Python code and cannot be used directly in this package. Use this function to translate the code to a request that can be handled by the package. For more details see vignette("translate")

Usage

cds_python_to_r(text, ...)

Arguments

Value

A named list that can be used as input for the functions cds_submit_job() and cds_estimate_costs()

Examples

python_code <-
"import cdsapi
dataset = \"reanalysis-era5-land\"
request = {
  \"variable\": [\"2m_dewpoint_temperature\"],
  \"year\": \"2025\",
  \"month\": \"01\",
  \"day\": [\"01\"],
  \"time\": [
    \"00:00\", \"01:00\", \"02:00\",
    \"03:00\", \"04:00\", \"05:00\",
    \"06:00\", \"07:00\", \"08:00\",
    \"09:00\", \"10:00\", \"11:00\",
    \"12:00\", \"13:00\", \"14:00\",
    \"15:00\", \"16:00\", \"17:00\",
    \"18:00\", \"19:00\", \"20:00\",
    \"21:00\", \"22:00\", \"23:00\"
  ],
  \"data_format\": \"netcdf\",
  \"download_format\": \"unarchived\"
}

client = cdsapi.Client()
client.retrieve(dataset, request).download()
"

cds_python_to_r(python_code)

Add or remove a star to a dataset, or list starred datasets

Description

Use stars to keep track of your favourite datasets. Use these functions to add or remove a star.

Usage

cds_starred(..., token = cds_get_token())

cds_assign_star(dataset, ..., token = cds_get_token())

cds_remove_star(dataset, ..., token = cds_get_token())

Arguments

Value

In case of cds_assign_star() returns the name of the starred dataset. In case of cds_starred() a vector of names of starred datasets. In case of cds_remove_star() returns NULL invisibly.

Examples

if (interactive() && cds_token_works()) {
  cds_assign_star("reanalysis-carra-single-levels")
  cds_starred()
  cds_remove_star("reanalysis-carra-single-levels")
}

Submit a download job for a dataset

Description

Submit a request to the Copernicus Climate Data Service to download (part of) a dataset. If the request is successful, a job identifier is returned which can be used to actually download the data (cds_download_jobs()).

Usage

cds_submit_job(
  dataset,
  ...,
  wait = TRUE,
  check_quota = TRUE,
  check_licence = TRUE,
  token = cds_get_token()
)

Arguments

Value

Returns a data.frame containing information about the submitted job.

Examples

if (interactive() && cds_token_works()) {
  job <- cds_submit_job(
      dataset        = "reanalysis-era5-pressure-levels",
      variable       = "geopotential",
      product_type   = "reanalysis",
      area           = c(n = 55, w = -1, s = 50, e = 10),
      year           = "2024",
      month          = "03",
      day            = "01",
      pressure_level = "1000",
      data_format    = "netcdf"
    )

  ## Or split into two separate steps:
  
  req <- cds_build_request(
      dataset        = "reanalysis-era5-pressure-levels",
      variable       = "geopotential",
      product_type   = "reanalysis",
      area           = c(n = 55, w = -1, s = 50, e = 10),
      year           = "2024",
      month          = "03",
      day            = "01",
      pressure_level = "1000",
      data_format    = "netcdf"
    )
  job <- cds_submit_job(req)
}