The hardware and bandwidth for this mirror is donated by METANET, the Webhosting and Full Service-Cloud Provider.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]metanet.ch.

Title: Search Download and Handle Data from Copernicus Climate Data Service
Version: 0.0.2
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: 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' '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-05 15:45:23 UTC; vries171
Author: Pepijn de Vries ORCID iD [aut, cre]
Maintainer: Pepijn de Vries <pepijn.devries@outlook.com>
Repository: CRAN
Date/Publication: 2025-10-09 07:40:12 UTC

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

Description

logo

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:


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

license

The license id you wish to accept.

revision

The revision number of the license you are accepting. Should always be the latest revision.

...

Ignored

token

An API key to be used for authentication. Will use cds_get_token() by default.

Value

Returns a data.frame containing the accepted license

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

scope

Scope of the licenses to be listed should be one of "all" (default), "dataset" or "portal".

...

Ignored

token

An API key to be used for authentication. Will use cds_get_token() by default.

Value

Returns a data.frame listing the accepted licenses.

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

token

An API key to be used for authentication. Will use cds_get_token() by default.

...

Ignored

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

dataset

The dataset name to be used for setting up a request.

...

Parameters for subsetting the dataset. Use cds_dataset_form() to inquiry which parameters and parameter values are available for a specific dataset. If left blank it will take default parameter values.

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

...

Ignored

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

token

An API key to be used for authentication. Will use cds_get_token() by default.

...

Ignored

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

dataset

The name of a dataset to be cited.

...

Ignored

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

dataset

A name of a dataset to explore

...

Ignored

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

job_id

Hexadecimal code used as identifier of a job. Identifies the job to be cancelled.

...

Ignored

token

An API key to be used for authentication. Will use cds_get_token() by default.

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

job_id

If a specific job identifier is listed here, only the files resulting from those jobs are downloaded. If left blank, all successful jobs are downloaded.

destination

Destination path to store downloaded files.

names

File names for the downloaded files. If missing, the cryptic hexadecimal file name is taken from the job.

...

Ignored

token

An API key to be used for authentication. Will use cds_get_token() by default.

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

dataset

A dataset name to be inspected

...

Parameters passed on to cds_build_request()

token

An API key to be used for authentication. Will use cds_get_token() by default.

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

token

An API key to be used for authentication. Will use cds_get_token() by default.

...

Ignored

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

...

Ignored

token

The API key you wish to set as an R option or to an evironment variable.

method

Method to store the API key. Should be either "option" (default) or "sysenv".

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

dataset

A specific dataset for which to list details. If missing all datasets are listed.

...

Ignored

search

A string containing free text search terms to look for in the available datasets.

keywords

A (vector of) string containing specific keywords. Should be listed in cds_catalogue_vocabulary()

page

When there are more search results than limit, results are paginated. Use page to specify which page to return starting at 0 (default).

limit

Use to limit the number of search results. Defaults to 50.

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

job_id

The id of a specific job, if you want the results for that job. If NULL (default) it is ignored.

status

Only return jobs with the status stated by this argument. Default is NULL meaning that jobs with any status are returned. Should be any of "accepted", "running", "successful", "failed", or "rejected".

limit

Use to limit the number of listed results. Defaults to 50.

...

Ignored

token

An API key to be used for authentication. Will use cds_get_token() by default.

Value

Returns a data.frame of submitted jobs.

Examples

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

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

...

Ignored

token

An API key to be used for authentication. Will use cds_get_token() by default.

dataset

Name of the dataset to assign a star to, or remove it from.

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

dataset

The dataset name to be downloaded

...

Subsetting parameters passed onto cds_build_request().

wait

A logical value indicating if the function should wait for the submitted job to finish. Set it to FALSE to continue without waiting

check_quota

Each account has a quota of data that can be downloaded. If this argument is set to TRUE (default) it is checked if the request doesn't exceed your quota. Set it to FALSE to skip this step and speed up the submission.

check_licence

Datasets generally require you to accept certain terms of use. If this argument is set to TRUE (default), it will be checked if you have accepted all required licences for the submitted request. Set it to FALSE to skip this step and speed up the submission.

token

An API key to be used for authentication. Will use cds_get_token() by default.

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"
    )
}

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.