example MARS language Old WEB-API New CDS-API (MARS like) New CDS-API ("beautified" - generated by ECDS)

TIGGE

Ensemble

Control Forecast

Single level

retrieve,
  class=ti,
  date=2024-02-01/to/2024-02-03,
  expver=prod,
  grid=0.2/0.2,
  levtype=sfc,
  model=glob,
  origin=ecmf,
  param=121/122,
  step=6/to/24/by/6,
  time=00:00:00,
  type=cf,
  target="output"

#!/usr/bin/env python
from ecmwfapi import ECMWFDataServer
server = ECMWFDataServer()

server.retrieve({
 
    "dataset": "tigge",
    "date": "2024-02-01/to/2024-02-03",
    "expver": "prod",
    "grid": "0.2/0.2",
    "levtype": "sfc",
    "origin": "ecmf",
    "param": "121/122",
    "step": "6/to/24/by/6",
    "time": "00:00:00",
    "type": "cf",
    "target": "output"
})

#!/usr/bin/env python
import cdsapi
client = cdsapi.Client()
            
dataset = "tigge-forecasts"

request = {
    "class": "ti",
    "date": "2024-02-01/2024-02-03",
    "expver": "prod",
    "grid": "0.2/0.2",
    "levtype": "sfc",
    "origin": "ecmf",
    "param": "121/122",
    "step": "6/to/24/by/6",
    "time": "00:00:00",
    "type": "cf"
}

target = "output"
client.retrieve(dataset, request, target)

#!/usr/bin/env python
import cdsapi
client = cdsapi.Client()

dataset = "tigge-forecasts"

request = {
    "year": ["2024"],
    "month": ["02"],
    "day": ["01", "02", "03"],
    "grid": "0.2/0.2",
    "level_type": "single_level",
    "origin": "ecmf",
    "variable": ["maximum_2m_temperature_in_the_last_6_hours",
       "minimum_2m_temperature_in_the_last_6_hours"],
    "leadtime_hour": [
        "6",
        "12",
        "18",
        "24"
    ],
    "time": "00:00:00",
    "forecast_type": "control_forecast",
    "data_format": "grib"
}

target = "output"
client.retrieve(dataset, request, target)

S2S

Ensemble

Control Forecast

Single level

retrieve,
  class=s2,
  date=2024-02-02,
  expver=prod,
  grid=1.5/1.5,
  levtype=sfc,
  model=glob,
  origin=ecmf,
  param=165/166,
  step=6/to/24/by/6,
  stream=enfo,
  time=00:00:00,
  type=cf,
  target="output"

#!/usr/bin/env python
from ecmwfapi import ECMWFDataServer
server = ECMWFDataServer()

server.retrieve(
    {
    "dataset": "s2s",
    "class": "s2",
    "date": "2022-05-02",
    "expver": "prod",
    "grid": "1.5/1.5",
    "levtype": "sfc",
    "origin": "ecmf",
    "param": "165/166",
    "step": "6/to/24/by/6",
    "time": "00:00:00",
    "stream": "enfo",
    "type": "cf",
    "target": "output"
    })

#!/usr/bin/env python
import cdsapi
client = cdsapi.Client()
            
dataset = "s2s-forecasts"

request = {
    "class": "s2",
    "date": "2022-05-02",
    "expver": "prod",
    "grid": "1.5/1.5",
    "levtype": "sfc",
    "origin": "ecmf",
    "param": "165/166",
    "step": "6/to/24/by/6",
    "time": "00:00:00",
    "stream": "enfo",
    "type": "cf"
}

target = "output"
client.retrieve(dataset, request, target)

#!/usr/bin/env python
import cdsapi
client = cdsapi.Client()

dataset = "s2s-forecasts"

request = {
    "origin": "ecmwf",
    "forecast_type": "control_forecast",
    "level_type": "single_level",
    "variable": [
        "10m_u_component_of_wind",
        "10m_v_component_of_wind"
    ],
    "year": "2022",
    "month": "05",
    "day": "02",
    "leadtime_hour": [
        "6",
        "12",
        "18",
        "24"
    ],
    "time": "00:00",
    "grid": "1.5/1.5",
    "data_format": "grib"
}

target = "output"
client.retrieve(dataset, request, target)

S2S

Ensemble

Control Re-Forecast

Single level

retrieve,
  class=s2,
  hdate=2022-05-02,
  date=2024-05-02,
  expver=prod,
  grid=1.5/1.5,
  levtype=sfc,
  model=glob,
  origin=ecmf,
  param=165/166,
  step=6/to/24/by/6,
  stream=enfh,
  time=00:00:00,
  type=cf,
  
target="output"

#!/usr/bin/env python
from ecmwfapi import ECMWFDataServer
server = ECMWFDataServer()

server.retrieve(
    {
    "dataset": "s2s",
    "class": "s2",
    "hdate": "2022-05-02",
    "date": "2024-05-02",
    "expver": "prod",
    "grid": "1.5/1.5",
    "levtype": "sfc",
    "origin": "ecmf",
    "param": "165/166",
    "step": "6/to/24/by/6",
    "time": "00:00:00",
    "stream": "enfh",
    "type": "cf",
    "target": "output"
    })

#!/usr/bin/env python
import cdsapi
client = cdsapi.Client()
            
dataset = "s2s-reforecasts"

request = {
    "class": "s2",
    "hdate": "2022-05-02",
    "date": "2024-05-02",
    "expver": "prod",
    "grid": "1.5/1.5",
    "levtype": "sfc",
    "origin": "ecmf",
    "param": "165/166",
    "step": "6/to/24/by/6",
    "time": "00:00:00",
    "stream": "enfh",
    "type": "cf"
}

target = "output"
client.retrieve(dataset, request, target)

#!/usr/bin/env python
import cdsapi
client = cdsapi.Client()

dataset = "s2s-reforecasts"

request = {
    "origin": "ecmwf",
    "forecast_type": "control_forecast",
    "level_type": "single_level",
    "variable": [
        "10m_u_component_of_wind",
        "10m_v_component_of_wind"
    ],
    "hyear": ["2022"],
    "hmonth": ["05"],
    "hday": ["02"],
    "leadtime_hour": [
        "6",
        "12",
        "18",
        "24"
    ],
    "time": "00:00",
    "year": "2024",
    "month": "05",
    "day": "02",
    "grid": "1.5/1.5",
    "data_format": "grib"
}

target = "output"
client.retrieve(dataset, request, target)

TIGGE

Ensemble

Perturbed Forecast

Single level

retrieve,
  class=ti,
  date=2024-02-02,
  expver=prod,
  grid=0.2/0.2,
  levtype=sfc,
  model=glob,
  origin=ecmf,
  param=121/122,
  step=6/to/24/by/6,
  time=00:00:00,
  type= pf,
  number=35/to/40/by/1,
  target="output"

#!/usr/bin/env python
from ecmwfapi import ECMWFDataServer
server = ECMWFDataServer()

server.retrieve(
    {
    "dataset": "tigge",
    "date": "2024-02-02",
    "expver": "prod",
    "grid": "0.2/0.2",
    "levtype": "sfc",
    "origin": "ecmf",
    "param": "121/122",
    "step": "6/to/24/by/6",
    "time": "00:00:00",
    "type": "pf",
    "number": "1/to/50/by/1",

    "target": "output"
    })

#!/usr/bin/env python
import cdsapi
client = cdsapi.Client()
            
dataset = "tigge-forecasts"

request = {
    "class": "ti",
    "date": "2024-02-02",
    "expver": "prod",
    "grid": "0.2/0.2",
    "levtype": "sfc",
    "origin": "ecmf",
    "param": "121/122",
    "step": "6/to/24/by/6",
    "time": "00:00:00",
    "type": "pf"
}

target = "output"
client.retrieve(dataset, request, target)

#!/usr/bin/env python
import cdsapi
client = cdsapi.Client()

dataset = "tigge-reforecasts"

request = {
    "forecast_type": "perturbed_forecast",
    "origin": "ecmwf",
    "level_type": "single_level",
    "year": "2024",
    "month": "02",
    "day": "02",
    "time": "00:00",
    "leadtime_hour": [
        "6",
        "12",
        "18",
        "24"
    ],
    "variable": [
        "maximum_2m_temperature_in_the_last_6_hours",
        "minimum_2m_temperature_in_the_last_6_hours"
    ],
    "grid": "0.2/0.2",
    "data_format": "grib"
}

target = "output"
client.retrieve(dataset, request, target)

S2S

Ensemble

Perturbed Forecast

Single level

retrieve,
  class=s2,
  date=2022-02-03,
  expver=prod,
  grid=1.5/1.5,
  levtype=sfc,
  model=glob,
  origin=ecmf,
  param=165/166,
  step=6/to/24/by/6,
  stream=enfo,
  time=00:00:00,
  type=pf,
  number=1/10/50,
  target="output"

#!/usr/bin/env python
from ecmwfapi import ECMWFDataServer
server = ECMWFDataServer()

server.retrieve(
    {
    "dataset": "s2s",
    "class": "s2",
    "date": "2022-02-03",
    "expver": "prod",
    "grid": "1.5/1.5",
    "levtype": "sfc",
    "origin": "ecmf",
    "param": "165/166",
    "step": "6/to/24/by/6",
    "time": "00:00:00",
    "stream": "enfo",
    "type": "pf",
    "number": "1/10/50",
    "target": "output"
    })

#!/usr/bin/env python
import cdsapi
client = cdsapi.Client()
            
dataset = "s2s-forecasts"

request = {
    "class": "s2",
    "date": "2022-02-03",
    "expver": "prod",
    "grid": "1.5/1.5",
    "levtype": "sfc",
    "origin": "ecmf",
    "param": "165/166",
    "step": "6/to/24/by/6",
    "time": "00:00:00",
    "stream": "enfo",
    "type": "pf"
}

target = "output"
client.retrieve(dataset, request, target)

#!/usr/bin/env python
import cdsapi
client = cdsapi.Client()

dataset = "s2s-reforecasts"

request = {
    "origin": "ecmwf",
    "forecast_type": "perturbed_forecast",
    "level_type": "single_level",
    "variable": [
        "10m_u_component_of_wind",
        "10m_v_component_of_wind"
    ],
    "year": "2022",
    "month": "02",
    "day": "03",
    "leadtime_hour": [
        "6",
        "12",
        "18",
        "24"
    ],
    "time": "00:00",
    "grid": "1.5/1.5",
    "data_format": "grib"
}

target = "output"
client.retrieve(dataset, request, target)

S2S

Ensemble

Perturbed Re-Forecast

Single level

retrieve,
  class=s2,
  hdate=2022-05-02,
  date=2024-05-02,
  expver=prod,
  grid=1.5/1.5,
  levtype=sfc,
  model=glob,
  origin=ecmf,
  param=165/166,
  step=6/to/24/by/6,
  stream=enfh,
  time=00:00:00,
  type=pf,
  number=1/to/10,
  area=70/-10/25/50,
  target="output"

#!/usr/bin/env python
from ecmwfapi import ECMWFDataServer
server = ECMWFDataServer()

server.retrieve(
    {
    "dataset": "s2s",
    "class": "s2",
    "hdate": "2022-05-02",
    "date": "2024-05-02",
    "expver": "prod",
    "grid": "1.5/1.5",
    "levtype": "sfc",
    "origin": "ecmf",
    "param": "165/166",
    "step": "6/to/24/by/6",
    "time": "00:00:00",
    "stream": "enfh",
    "type": "pf",
    "number": "1/to/10",
    "area": "70/-10/25/50",
    "target": "output"
    })

#!/usr/bin/env python
import cdsapi
client = cdsapi.Client()
            
dataset = "s2s-reforecasts"

request = {
    "class": "s2",
    "hdate": "2022-05-02",
    "date": "2024-05-02",
    "expver": "prod",
    "grid": "1.5/1.5",
    "levtype": "sfc",
    "origin": "ecmf",
    "param": "165/166",
    "step": "6/to/24/by/6",
    "time": "00:00:00",
    "stream": "enfh",
    "type": "pf",
    "area": "70/-10/25/50"
}

target = "output"
client.retrieve(dataset, request, target)

#!/usr/bin/env python
import cdsapi
client = cdsapi.Client()

dataset = "s2s-reforecasts"

request = {
    "origin": "ecmwf",
    "forecast_type": "perturbed_forecast",
    "level_type": "single_level",
    "variable": [
        "10m_u_component_of_wind",
        "10m_v_component_of_wind"
    ],
    "hyear": ["2022"],
    "hmonth": ["05"],
    "hday": ["02"],
    "leadtime_hour": [
        "6",
        "12",
        "18",
        "24"
    ],
    "time": "00:00",
    "year": "2024",
    "month": "05",
    "day": "02",
    "data_format": "grib",
    "area": [70, -10, 25, 50],
    "grid": "1.5/1.5",
    "data_format": "grib"
}

target = "output"
client.retrieve(dataset, request, target)

TIGGE

Ensemble

Control Forecast

Pressure levels

retrieve,
  class=ti,
  date=2024-02-01,
  expver=prod,
  levtype=pl,
levelist=200/250/300/500/700/850/925/1000,
  model=glob,
  origin=ecmf,
  param=130/131/132/133/156,
  step=6/to/24/by/6,
  time=00:00:00,
  type=cf,
  target="output"

#!/usr/bin/env python
from ecmwfapi import ECMWFDataServer
server = ECMWFDataServer()

server.retrieve({
    "dataset": "tigge",
    "class": "ti",
    "date": "2024-02-01",
    "expver": "prod",
    "levtype": "pl",
    "levelist": "200/250/300/500/700/850/925/1000",
    "model": "global",
    "origin": "ecmf",
    "param": "130/131/132/133/156",
    "step": "6/to/24/by/6",
    "time": "00:00:00",
    "type": "cf",

    "target": "output"
})

#!/usr/bin/env python
import cdsapi
client = cdsapi.Client()
            
dataset = "tigge-forecasts"

request = {
    "class": "ti",
    "date": "2024-02-01",
    "expver": "prod",
    "levtype": "pl",
    "levelist": "200/250/300/500/700/850/925/1000",
    "origin": "ecmf",
    "param": "130/131/132/133/156",
    "step": "6/to/24/by/6",
    "time": "00:00:00",
    "type": "cf"
}

target = "output"
client.retrieve(dataset, request, target)

#!/usr/bin/env python
import cdsapi
client = cdsapi.Client()

dataset = "tigge-forecasts"

request = {
    "forecast_type": "control_forecast",
    "origin": "ecmwf",
    "level_type": "pressure",
    "level_values": [
        "200_hpa",
        "250_hpa",
        "300_hpa",
        "500_hpa",
        "700_hpa",
        "850_hpa",
        "925_hpa",
        "1000_hpa"
    ],
    "year": "2024",
    "month": "02",
    "day": "01",
    "time": "00:00",
    "leadtime_hour": [
        "6",
        "12",
        "18",
        "24"
    ],
    "variable": [
        "geopotential_height",
        "specific_humidity",
        "temperature",
        "u_component_of_wind",
        "v_component_of_wind"
    ],
    "data_format": "grib"
}

target = "output"
client.retrieve(dataset, request, target)

S2S

Ensemble

Perturbed Re-Forecast

Oceanic

retrieve,
  class=s2,
  dataset=s2s,
  date=2024-05-02,
  expver=prod,
  hdate=2022-05-02,
  levtype=o2d,
  model=glob,
  number=1/2/3/4/5/6/7/8/9/10,
  origin=ecmf,
  param=151145/174098,
  step=24-48/48-72,
  stream=enfh,
  time=00:00:00,
  type=pf,
  target="output"

#!/usr/bin/env python
from ecmwfapi import ECMWFDataServer
server = ECMWFDataServer()

server.retrieve(
    {
    "class": "s2",
    "dataset": "s2s",
    "date": "2024-05-02",
    "expver": "prod",
    "hdate": "2022-05-02",
    "levtype": "o2d",
    "model": "glob",
    "origin": "ecmf",
    "param": "151145/174098",
    "step": "24-48/48-72",
    "stream": "enfh",
    "time": "00:00:00",
    "type": "pf",
    "number": "1/2/3/4/5/6/7/8/9/10",
    "target": "output"
    })

#!/usr/bin/env python
import cdsapi
client = cdsapi.Client()
            
dataset = "s2s-reforecasts"

request = {
    "class": "s2",
    "date": "2024-05-02",
    "hdate": "2022-05-02",
    "levtype": "o2d",
    "expver": "prod",
    "levtype": "o2d",
    "origin": "ecmf",
    "param": "151145/174098",
    "step": "24-48/48-72",
    "time": "00:00:00",
    "type": "pf"
}

target = "output"
client.retrieve(dataset, request, target)

#!/usr/bin/env python
import cdsapi
client = cdsapi.Client()

dataset = "s2s-reforecasts"

request = {
    "origin": "ecmwf",
    "forecast_type": "perturbed_forecast",
    "level_type": "oceanic",
    "variable": [
        "sea_ice_thickness",
        "sea_surface_height"
    ],
    "hyear": ["2022"],
    "hmonth": ["05"],
    "hday": ["02"],
    "leadtime_hour": [
        "24_48",
        "48_72"
    ],
    "time": "00:00",
    "year": "2024",
    "month": "05",
    "day": "02",
    "data_format": "grib"
}

target = "output"
client.retrieve(dataset, request, target)

Notes

For S2S and TIGGE perturbed forecast (type=pf) webAPI offers "number" keyword for selection of ensemble members, ECDS doesn't offer this and one is forced to download all ens members.

For example,:

- TIGGE, origin=ecmf;type=PF, ~99% of requests retrieve all ens members
- S2S forecast, origin=ecmf;type=PF, only ~10 % of requests retrieve 50 or 100 ens members
- S2S re-forecast, origin=ecmf; type=PF, only ~48% of requests retrieve all ens members
Public data portal is notably more responsive (quicker) than ECDS data portal (for selection of keys / variables) !
CDSAPI request doesn't contain MARS output and therefore it is more difficult to debug erroneous requests in comparison to webPI !

The examples are provided for most popular requests (with highest number of users) obtained from this dashboard: https://splunk.ecmwf.int/en-US/app/ecmwf_mars/migration_to_cds_popularity_table