DOCSEARCHbyAlgolia
Submit Docs

cdsapi Python Client

repository·master·Indexed 43 days ago

https://github.com/ecmwf/cdsapi

A Python client for programmatically accessing and downloading meteorological datasets, such as ERA5, from the Copernicus Climate Data Store (CDS). Includes instructions for installation via pip, configuration using ~/.cdsapirc, and usage of the cdsapi.Client.retrieve() method, as well as a dockerized version for data retrieval.

Tokens
981
Snippets
5
Records
5
Agent score
6%

What's inside cdsapi

  1. Configure the CDS API client

    master

    To use the API, you must create a configuration file named ~/.cdsapirc containing your Personal Access Token.

    1. Retrieve your Personal Access Token from your profile on the CDS portal: https://cds.climate.copernicus.eu/profile
    2. Create or edit the ~/.cdsapirc file with the following format:

    Note: You must also agree to the Terms and Conditions of every dataset you intend to download on the CDS portal.

    url: https://cds.climate.copernicus.eu/api
key: <PERSONAL-ACCESS-TOKEN>

  3. Use the dockerized version of cdsapi

    master

    To use cdsapi via Docker, you must provide a JSON request file containing your API credentials and the specific data parameters you wish to retrieve. The container expects the request file at /input/request.json and will save the downloaded data to the /output directory.

    1. Prepare the request JSON

    Create a JSON file (e.g., request.json) with the following structure:

    • url: The CDS API endpoint.
    • uuid: Your user ID.
    • key: Your user key.
    • variable: The dataset identifier.
    • options: A dictionary of parameters for the request (e.g., date, time, format).
    • filename: The desired name for the downloaded file.

    2. Run the Docker container

    Execute the docker run command, mounting your local request file to /input/request.json and your current working directory to /output to retrieve the file locally.

    {
  "url": "https://cds.climate.copernicus.eu/api/v2",
  "uuid": "<user id>",
  "key": "<user key>",
  "variable": "reanalysis-era5-pressure-levels",
  "options": {
    "variable": "temperature",
    "pressure_level": "1000",
    "product_type": "reanalysis",
    "date": "2017-12-01/2017-12-31",
    "time": "12:00",
    "format": "grib"
  },
  "filename":"test.grib"
}

  4. Use cdsapi.Client to retrieve data

    master

    The primary way to interact with the CDS is by instantiating cdsapi.Client() and calling the .retrieve() method. The .retrieve() method takes the dataset name, a dictionary of request parameters, and a target filename.

    Example retrieving ERA5 pressure level data:

    import cdsapi
cds = cdsapi.Client()
cds.retrieve('reanalysis-era5-pressure-levels', {
           "variable": "temperature",
           "pressure_level": "1000",
           "product_type": "reanalysis",
           "date": "2017-12-01/2017-12-31",
           "time": "12:00",
           "format": "grib"
       }, 'download.grib')

  5. Run the cdsapi Docker container

    master

    Run the following command to execute a data retrieval request using a Docker image. Ensure you replace <YOUR REPO> with the actual image name.

    This command uses volume mounts (-v) to map your local request.json to the container's /input directory and maps your current directory to the container's /output directory so the downloaded file is saved to your host machine.

    docker run -it --rm \
  -v $(pwd)/request.json:/input/request.json \
  -v $(pwd)/.:/output \
  <YOUR REPO>/cdsretrieve