How to use the CDS API with curl

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!

IRead Fun