- Created by Bojan Kasic, last modified on Apr 08, 2026
| example | MARS language | Old WEB-API | New CDS-API (MARS like) | New CDS-API ("beautified" - generated by ECDS) |
|---|---|---|---|---|
TIGGE Ensemble Control Forecast Single level |
MARS request Expand source
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" |
Old webAPI request Expand source
#!/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"
})
|
New CDS-API request (MARS syntax) Expand source
#!/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)
|
New CDS-API request (ECDS generated) Expand source
#!/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 |
MARS request Expand source
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" |
Old webAPI request Expand source
#!/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"
})
|
New CDS-API request (MARS syntax) Expand source
#!/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)
|
New CDS-API request (ECDS generated) Expand source
#!/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 |
MARS request Expand source
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" |
Old webAPI request Expand source
#!/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"
})
|
New CDS-API request (MARS syntax) Expand source
#!/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)
|
New CDS-API request (ECDS generated) Expand source
#!/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
|
MARS request Expand source
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" |
Old webAPI request Expand source
#!/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"
})
|
New CDS-API request (MARS syntax) Expand source
#!/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)
|
New CDS-API request (ECDS generated) Expand source
#!/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
|
MARS request Expand source
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" |
Old webAPI request Expand source
#!/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"
})
|
New CDS-API request (MARS syntax) Expand source
#!/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)
|
New CDS-API request (ECDS generated) Expand source
#!/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
|
MARS request Expand source
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" |
Old webAPI request Expand source
#!/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"
})
|
New CDS-API request (MARS syntax) Expand source
#!/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)
|
New CDS-API request (ECDS generated) Expand source
#!/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 |
MARS request Expand source
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" |
Old webAPI request Expand source
#!/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"
})
|
New CDS-API request (MARS syntax) Expand source
#!/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)
|
New CDS-API request (ECDS generated) Expand source
#!/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
|
MARS request Expand source
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" |
Old webAPI request Expand source
#!/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"
})
|
New CDS-API request (MARS syntax) Expand source
#!/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)
|
New CDS-API request (ECDS generated) Expand source
#!/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
- No labels
2 Comments
Joshua Talib
Thanks for this.
Regarding 's2s-forecast' examples, am I right that given forecast data is requested at a 1.5 degree resolution, requesting a grid of [0.5,0.5] would interpolate the data to the finer grid? It may be best to request a grid resolution that does not require interpolation, i.e. [1.5,1.5] and then make clear to users that they can interpolate to finer grids if they choose to.
Josh
Bojan Kasic
Corrected to 1.5 for atmospheric S2S retrievals. Thanks for pointing to this!