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 |
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
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:
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
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
|
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 |
... |
Ignored |
token |
An API key to be used for authentication. Will use
|
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
|
... |
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 |
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
|
... |
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
|
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
|
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 |
token |
An API key to be used for authentication. Will use
|
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
|
... |
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 |
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
|
page |
When there are more search results than |
limit |
Use to limit the number of search results. Defaults to |
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 |
status |
Only return jobs with the status stated by this argument. Default is |
limit |
Use to limit the number of listed results. Defaults to |
... |
Ignored |
token |
An API key to be used for authentication. Will use
|
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
|
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 |
wait |
A |
check_quota |
Each account has a quota of data that can be downloaded.
If this argument is set to |
check_licence |
Datasets generally require you to accept certain terms of use.
If this argument is set to |
token |
An API key to be used for authentication. Will use
|
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"
)
}