The Climate Data Store (CDS) Application Program Interface (API) is a service providing programmatic access to CDS data like ERA5.
ERA5 is the fifth generation ECMWF reanalysis for the global climate and weather for the past 8 decades. Data is available from 1940 onwards. ERA5 replaces the ERA-Interim reanalysis.
The CDS has provided a python based API client library cdsapi. It provides support for both Python 2.7.x and Python 3.
Python cdsapi single levels example
code from https://cds.climate.copernicus.eu/cdsapp#!/dataset/reanalysis-era5-single-levels?tab=form
import cdsapi
c = cdsapi.Client()
c.retrieve(
'reanalysis-era5-single-levels',
{
'product_type': 'reanalysis',
'format': 'grib',
'variable': [
'2m_dewpoint_temperature', '2m_temperature', 'convective_available_potential_energy',
'convective_precipitation', 'large_scale_precipitation', 'mean_sea_level_pressure',
'total_precipitation',
],
'year': '2024',
'month': [
'03', '04',
],
'day': [
'01', '02', '30',
'31',
],
'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',
],
'area': [
50, 90, 20,
120,
],
},
'download.grib')
Python cdsapi pressure levels example
code from https://cds.climate.copernicus.eu/cdsapp#!/dataset/reanalysis-era5-pressure-levels?tab=form
import cdsapi
c = cdsapi.Client()
c.retrieve(
'reanalysis-era5-pressure-levels',
{
'product_type': 'reanalysis',
'format': 'grib',
'pressure_level': [
'500', '700',
],
'year': '2024',
'month': [
'03', '04',
],
'day': [
'01', '02', '30',
'31',
],
'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',
],
'area': [
50, 90, 20,
120,
],
'variable': [
'divergence', 'geopotential',
],
},
'download.grib')
We can also use the CDS API without Python. Here I will show you how to use the CDS API with curl to download ERA5 data.
Check API status
curl https://cds.climate.copernicus.eu/api/v2/status.json
{
"info": ["Welcome to the CDS"],
"warning": []
}
Authorization Required
curl -X POST -H "Content-Type: application/json"
https://cds.climate.copernicus.eu/api/v2/resources/reanalysis-era5-pressure-levels
<html>
<head><title>401 Authorization Required</title></head>
<body>
<center><h1>401 Authorization Required</h1></center>
<hr><center>nginx/1.20.2</center>
</body>
</html>
If you don't have an account, please self register at the CDS registration page and go to the steps below.
If you are not logged, please login and go to the step below.
Copy the key displayed at https://cds.climate.copernicus.eu/api-how-to
Agreed to the required terms and conditions
curl -X POST -H "Content-Type: application/json"
-u 123456:2d0b6cac-e6cb-4d1b-85df-1234560f4dd6
-d '{ "variable": "temperature", "pressure_level": "1000", "product_type": "reanalysis", "date": "2017-12-01/2017-12-02", "time": "12:00", "format": "grib" }'
https://cds.climate.copernicus.eu/api/v2/resources/reanalysis-era5-pressure-levels
{
"message": "Client has not agreed to the required terms and conditions.",
"url": "http://copernicus-climate.eu/exc/missing-terms",
"reason": "Client has not agreed to the required terms and conditions.",
"context": {
"required_terms": [{
"title": "Licence to use Copernicus Products",
"url": "https://cds.climate.copernicus.eu/cdsapp/#!/terms/licence-to-use-copernicus-products",
"reason": "missing"
}]
},
"permanent": false,
"who": "client"
}
To access this resource, you first need to accept the terms of "Licence to use Copernicus Products" at https://cds.climate.copernicus.eu/cdsapp/#!/terms/licence-to-use-copernicus-products
Request will queued
curl -X POST -H "Content-Type: application/json"
-u 123456:2d0b6cac-e6cb-4d1b-85df-1234560f4dd6
-d '{ "variable": "temperature", "pressure_level": "1000", "product_type": "reanalysis", "date": "2017-12-01/2017-12-02", "time": "12:00", "format": "grib" }'
https://cds.climate.copernicus.eu/api/v2/resources/reanalysis-era5-pressure-levels
{
"state": "queued",
"request_id": "baa0698c-b035-4ace-a463-a3ba4639df69",
"specific_metadata_json": {
"top_request_origin": "api"
}
}
Check request_id state
curl -u 123456:2d0b6cac-e6cb-4d1b-85df-1234560f4dd6
https://cds.climate.copernicus.eu/api/v2/tasks/baa0698c-b035-4ace-a463-a3ba4639df69
{
"state": "completed",
"request_id": "baa0698c-b035-4ace-a463-a3ba4639df69",
"location": "https://download-0001-clone.copernicus-climate.eu/cache-compute-0001/cache/data6/adaptor.mars.internal-1713276220.7536583-952-1-baa0698c-b035-4ace-a463-a3ba4639df69.grib",
"content_length": 4153200,
"content_type": "application/x-grib",
"sent_to_rmq_at": "2024-04-16T14:03:40.448Z",
"specific_metadata_json": {
"top_request_origin": "api"
}
}
Download the file at location
curl -o era5-test.grib https://download-0001-clone.copernicus-climate.eu/cache-compute-0001/cache/data6/adaptor.mars.inter
nal-1713276220.7536583-952-1-baa0698c-b035-4ace-a463-a3ba4639df69.grib
That's all!
