ecmwf-opendata (Rust)

Rust client for ECMWF Open Data.

API documentation (docs.rs): https://docs.rs/ecmwf-opendata

This crate is a Rust re-implementation of the core functionality of the upstream Python project ecmwf-opendata:

• Build MARS-like requests (keyword/value pairs)
• Resolve request → data URLs
• Download whole files, or download selected fields via the .index sidecar using HTTP Range requests

Chinese documentation: see README.zh-CN.md.

Install

cargo add ecmwf-opendata

Library usage

1) Python-like Client(...) options

Python:

client = Client(
    source="ecmwf",
    model="ifs",
    resol="0p25",
    preserve_request_order=False,
    infer_stream_keyword=True,
)

Rust:

use ecmwf_opendata::{Client, ClientOptions};

let opts = ClientOptions {
    source: "ecmwf".to_string(),
    model: "ifs".to_string(),
    resol: "0p25".to_string(),
    preserve_request_order: false,
    infer_stream_keyword: true,
    ..ClientOptions::default()
};

let client = Client::new(opts)?;
# Ok::<(), ecmwf_opendata::Error>(())

source can be a known mirror ("ecmwf", "aws", "azure", "google") or a custom base URL ("https://...").

2) Request builder (kwargs-ish)

use ecmwf_opendata::{Client, ClientOptions, Request};

let client = Client::new(ClientOptions::default())?;

let req = Request::new()
    .r#type("fc")
    .param("msl")
    .step(240)
    .target("data.grib2");

let result = client.retrieve_request(req)?;
println!("Downloaded {} bytes", result.size_bytes);
# Ok::<(), ecmwf_opendata::Error>(())

3) retrieve_pairs: strongest “kwargs/dict” feel

use ecmwf_opendata::{Client, ClientOptions};

let client = Client::new(ClientOptions::default())?;

let result = client.retrieve_pairs([
    ("type", "fc".into()),
    ("param", "msl".into()),
    ("step", 240.into()),
    ("target", "data.grib2".into()),
])?;

println!("{}", result.datetime);
# Ok::<(), ecmwf_opendata::Error>(())

4) Macro: closest to Python client.retrieve(time=..., ...)

use ecmwf_opendata::{Client, ClientOptions, retrieve};

let client = Client::new(ClientOptions::default())?;

let steps: Vec<i32> = (12..=360).step_by(12).collect();

let result = retrieve!(
    client,
    time = 0,
    stream = "enfo",
    type = "ep",
    step = steps,
    levelist = 850,
    param = [
        "ptsa_gt_1stdev",
        "ptsa_gt_1p5stdev",
        "ptsa_gt_2stdev",
        "ptsa_lt_1stdev",
        "ptsa_lt_1p5stdev",
        "ptsa_lt_2stdev",
    ],
    target = "data.grib2",
)?;

println!("{}", result.datetime);
# Ok::<(), ecmwf_opendata::Error>(())

5) GUI/config style: string key/value inputs

If your UI stores values as strings, build a request with Request::from_str_pairs.

use ecmwf_opendata::{Client, ClientOptions, Request};

let client = Client::new(ClientOptions::default())?;

// Example: values come from text fields
let req = Request::from_str_pairs([
    ("time", "0"),
    ("stream", "enfo"),
    ("type", "ep"),
    ("step", "12,24,36"),
    ("levelist", "850"),
    ("param", "tpg1,tpg5,10fgg10"),
    ("target", "data.grib2"),
]);

let result = client.retrieve_request(req)?;
println!("{}", result.datetime);
# Ok::<(), ecmwf_opendata::Error>(())

CLI

This repository also includes a small CLI example (as a Cargo example target).

cargo run --example cli -- retrieve data.grib2
cargo run --example cli -- download data.grib2

Example: realtime_forecast 🔁

A convenience example that mirrors a typical operational script: it spawns threads to download several meteorological variables for grouped forecast step ranges and writes files named <variable>_<YYYYmmddHH>_<start>-<end>.grib2 under <main_dir>/realtimeforecast/<YYYYmmddHH>/.

Usage:

cargo run --example realtime_forecast -- <main_dir> [<YYYYmmddHH>]

• If <YYYYmmddHH> is omitted the example picks the nearest 00/12 UTC cycle automatically.
• The example downloads the following (variable, levtype) pairs in parallel: 10u/srf, 10v/srf, 2t/srf, msl/srf, tp/srf, gh/pl, u/pl, v/pl.
• Forecast steps are grouped into six bands (0-24, 27-48, 51-72, 75-96, 99-120, 123-144 hours) and each group is written to an individual file named with the group's start/end hours.
• The program skips existing non-empty files and prints errors for failed downloads; you can edit the example to enable retries or change the source mirror.

Notes:

• The example constructs a Client using ClientOptions (see the source in examples/realtime_forecast.rs); edit the source or other fields there to change behavior (e.g. source = "ecmwf" | "aws" | "azure" | "google").
• The example is intentionally minimal; feel free to adapt it to add retries, timeouts, logging, or a command-line flag to select the source.

Notes / limitations

• This is intentionally a “core features” port; it does not aim to fully replicate every upstream Python feature.
• latest() probing depends on endpoint availability. If it fails, specify date/time explicitly.
• Data usage is subject to ECMWF Open Data terms (including attribution requirements).