Sign in
Ctrl K


Tool for downloading Land Surface Model input data

74 commits | Last commit 4 months ago

What zampy can do for you


Tool for downloading Land Surface Model (LSM) input data.

Named after Zam; the Avestan language term for the Zoroastrian concept of "earth".

github license badge Documentation Status build workflow scc badge


zampy is designed to retrieve data for LSM model input. It can help you prepare the data within the following steps:

  1. Download the data for the specified location(s) / geographical area.
  2. Ingest data into unified (zampy) format.
  3. Load the variables in a standardized way (standardized names & standardized units).
  4. Convert the data to standard formats:
    • ALMA / PLUMBER2's ALMA formatted netCDF.
    • CMOR formatted netCDF.

(Note: items in italic will not be worked on for now/low priority, but we want to allow space for these in the future.)

Getting start


workflow pypi badge supported python versions

To install the latest release of zampy, do:

python3 -m pip install zampy

To install the in-development version from the GitHub repository, do:

python3 -m pip install git+


Zampy needs to be configured with a simple configuration file.

You need to create this file under your user home directory:


The configuration file should contain the working_directory, for instance:

working_directory: /path_to_a_working_directory/  #for example: /home/bart/Zampy

If you need access to data on CDS or ADS server, you should add your CDS or ADS credentials to zampy_config.yml:

  url:  # for example
  key:  # for example 12345:xhashd-232jcsha-dsaj429-cdjajd29319
  url:  # for example
  key:  # for example 12345:xhashd-232jcsha-dsaj429-cdjajd29319

About how to create CDS or ADS credentials, check the section below.

How to use zampy

We recommend our users to use zampy with recipes.

A "recipe" is a file with yml extension, it defines:

  • data downloading
    • time extent.
    • spatial location / bounding box.
    • datasets to be downloaded
      • variables within datasets
  • data conversion
    • convert to desired conventions
    • output frequency
    • output resolution

A sample recipe can be found in the documentation.

When you have your reciped created and saved on your disk, you can execute your recipe by running the following code in your shell:

zampy /path_to_recipe/sample_recipe.yml

We also provide python API for you to intereact with zampy. You can find the example notebooks for each supported dataset here.

Instructions for CDS/ADS datasets

To download the following datasets, users need access to CDS/ADS via cdsapi/adsapi:

  • CDS
    • ERA5
    • ERA5 land
    • LAI
    • land cover
  • ADS
    • CAMS EGG4 (e.g. co2)

To generate these API keys, you need to be a registered user on CDS via the registration page, or on ADS via the registration page.

Before submitting any request with zampy, please put your cdsapi/adsapi credentials in zampy_config.yml. Here is a short instruction about how to find your CDS/ADS API key. You can skip the steps related to .cdsapirc and simply add the key to zampy_config.yml.

Agree to the Terms of Use on CDS/ADS

When downloading a dataset for the first time, it is necessary to agree to the Terms of Use of every datasets that you intend to download. This can only be done via the CDS/ADS website. When you try to download these datasets, you will be prompted to go to the terms of use and accept them.


This package was developed by the Netherlands eScience Center. Development was supported by the Netherlands eScience Center under grant number NLESC.ASDI.2020.026.

No keywords available
Programming language
  • Python 100%
</>Source code


Yang Liu
Fakhereh Alidoost
Yijian Zeng
Lead Applicant
University of Twente
Zhongbo Su

Related projects


Accelerating Process Understanding for Ecosystem Functioning under Extreme Climates with Physics-Aware Machine Learning

Updated 11 months ago
In progress

Related software



A python package for running the STEMMUS-SCOPE model

Updated 11 months ago



Integrated code of SCOPE and STEMMUS

Updated 2 weeks ago