# How to use the CDS API with curl
The **Climate Data Store (CDS) Application Program Interface (**[**API**](https://cds.climate.copernicus.eu/api-how-to)**)** is a service providing programmatic access to CDS data like **ERA5**.
[**ERA5**](https://cds.climate.copernicus.eu/cdsapp#!/dataset/reanalysis-era5-single-levels?tab=overview) 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](https://github.com/ecmwf/cdsapi) `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](https://cds.climate.copernicus.eu/cdsapp#!/dataset/reanalysis-era5-single-levels?tab=form)
```python
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](https://cds.climate.copernicus.eu/cdsapp#!/dataset/reanalysis-era5-pressure-levels?tab=form)
```python
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
```bash
curl https://cds.climate.copernicus.eu/api/v2/status.json
{
"info": ["Welcome to the CDS"],
"warning": []
}
```
## Authorization Required
```bash
curl -X POST -H "Content-Type: application/json"
https://cds.climate.copernicus.eu/api/v2/resources/reanalysis-era5-pressure-levels
401 Authorization Required
401 Authorization Required
nginx/1.20.2
```
> 1. If you don't have an account, please self register at the [CDS registration](https://cds.climate.copernicus.eu/user/register?destination=%2F%23!%2Fhome) [page and go to t](https://cds.climate.copernicus.eu/user/register?destination=%2F%23!%2Fhome)he steps below.
>
> 2. If you are not logged, please [login](https://cds.climate.copernicus.eu/user/login?destination=%2F%23!%2Fhome) [and g](https://cds.climate.copernicus.eu/user/login?destination=%2F%23!%2Fhome)o to the step below.
>
> 3. Copy the key displayed at [https://cds.climate.copernicus.eu/api-how-to](https://cds.climate.copernicus.eu/api-how-to)
>
## Agreed to the required terms and conditions
```bash
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](https://cds.climate.copernicus.eu/cdsapp/#!/terms/licence-to-use-copernicus-products)
## Request will queued
```bash
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
```bash
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
```bash
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!