Request JSON Format

A request file has two top-level sections: files_query_options (which files to find) and extraction_query_options (what to do with them).

{
    "files_query_options": {
        "dataset": "cordex",
        "domain": "EUR-11",
        "scenario": "historical",
        "temporal_resolution": "3hr",
        "variable": "tas",
        "institution": "GERICS",
        "gcm": "MPI-M-MPI-ESM-LR",
        "rcm": "GERICS-REMO2015",
        "ensemble_member": "r3i1p1",
        "start": "196801010100",
        "end": "196803010100"
    },
    "extraction_query_options": {
        "selected_option": "nearest_grid_point",
        "latitude": 50.0,
        "longitude": 8.0
    }
}

Requests like this are generated for you by zephyr-frontend (see Using the Web Interface) — this page documents the schema so you can also write or script requests by hand.

files_query_options

Which fields are required depends on dataset, since each dataset is stored under a different directory layout (see src/zephyr/path_constructor.py):

dataset

Required fields (besides dataset, start, end)

era5_cds

variable, temporal_resolution, grid

era5-land_cds

variable, temporal_resolution, grid

cerra

variable, temporal_resolution, grid

cerra-land

variable, temporal_resolution, grid

cmip5

scenario, temporal_resolution, variable, gcm, ensemble_member

cmip6

scenario, temporal_resolution, variable, gcm, ensemble_member, grid

cordex

domain (default EUR-11), scenario, temporal_resolution, variable, institution, gcm, rcm, ensemble_member

cordex-reklies

same as cordex

Note

dataset must exactly match one of the keys above — this is also the string the frontend’s dataset picker sends, kept in sync with iac-metadata’s datasets.json.

Common fields:

  • start / end — date range to extract, formatted to match the granularity of the dataset’s filenames (e.g. "197001" for monthly ERA5, "20150101" for daily CMIP6, "196801010100" for 3-hourly CORDEX). Zephyr matches these against the date range encoded in each file’s name and returns every file overlapping [start, end].

  • Any field can hold multiple values as a list, e.g. "variable": ["tas", "pr"] or "ensemble_member": ["r1i1p1f1", "r2i1p1f1"]. Zephyr builds one path per combination (the Cartesian product across all list-valued fields) and processes every matching file. A pluralized key ("variables": [...]) is also accepted and takes precedence over the singular form if both are present.

extraction_query_options

selected_option chooses one of two extraction methods:

{
    "selected_option": "nearest_grid_point",
    "latitude": 50.0,
    "longitude": 8.0
}

Extracts the time series of the grid cell closest to (latitude, longitude). Output filename prefix: interp_<lat>_<lon>.

{
    "selected_option": "rectangular_clipping",
    "min_latitude": 45.0,
    "max_latitude": 55.0,
    "min_longitude": 5.0,
    "max_longitude": 15.0
}

Clips a rectangular bounding box. Output filename prefix: rect_<minlat>-<maxlat>_<minlon>-<maxlon>.

Coordinates are always in regular latitude/longitude, regardless of the dataset’s native grid — see Supported Datasets for how rotated and LCC grids are handled before extraction.