ecmwf-opendata Python Package

ECMWF uses stream and type to categorize forecasting systems and products.

Systems:

• HRES: High Resolution Forecast.
• ENS: Ensemble Forecasts.
• SEAS: Seasonal Forecast.

Common Types:

• HRES: fc (Forecast).
• ENS: cf (Control), pf (Perturbed), em (Ensemble mean), es (Ensemble standard deviation), ep (Probabilities).

Common Streams:

• oper: HRES atmospheric (00/12 UTC).
• wave: HRES ocean waves.
• enfo: ENS atmospheric.
• waef: ENS ocean waves.
• scda: HRES atmospheric (06/18 UTC).
• scwv: HRES ocean waves (06/18 UTC).

If infer_stream_keyword is set to True in the Client, you only need to specify stream=wave for ocean products; the library will infer the rest from type and time.

All dates and times are in UTC. You can use strings, integers, or Python datetime objects.

Date Formats:

• Strings: '20220125', '2022-01-25', or '2022-01-25 12:00:00'.
• Integers: 20220125.
• datetime.date or datetime.datetime objects.
• Relative offsets: date=0 (today), date=-1 (yesterday).

Time Formats:

• Integers: 0, 6, 12, 18.
• Strings: '12', '1200'.
• datetime.time objects.

Note: If time is not specified, it is extracted from the date string. If date and time are omitted, the library fetches the most recent available data.

Install the ecmwf-opendata Python package from PyPI using pip.

pip install ecmwf-opendata

The client automatically retries transient HTTP errors (429, 500, 502, 503, 504, 408) and connection errors. You can customize this behavior during Client initialization.

Parameters:

• maximum_retries: Max attempts (default: 500).
• retry_after: Seconds to wait between retries (default: 120).
• use_server_retry_after: If True (default), honors the server's Retry-After header. If the header is missing, it falls back to retry_after.

retry_after can also be a tuple (min, max, ratio) for incremental backoff.

from ecmwf.opendata import Client

client = Client(
    source="ecmwf",
    maximum_retries=500,
    retry_after=120,
    use_server_retry_after=True,
)

# Using incremental backoff: start at 10s, double each time, cap at 300s
client = Client(
    source="ecmwf",
    retry_after=(10, 300, 2),
)

The latest() method returns the date and time of the most recent matching forecast without actually downloading any data. It accepts the same parameters as retrieve().

from ecmwf.opendata import Client

client = Client(source="ecmwf")

print(client.latest(
    type="fc",
    step=24,
    param=["2t", "msl"],
    target="data.grib2",
))

The download() method accepts the same parameters as retrieve(), but it downloads the entire data file from the server. It ignores specific filtering keywords like param, levelist, or number. Use this when you want the complete file rather than specific subsets.

from ecmwf.opendata import Client

client = Client(source="ecmwf")

client.download(
    param="msl",
    type="fc",
    step=24,
    target="data.grib2",
)

The retrieve() method is the primary way to fetch specific meteorological data. You can pass a request object or provide arguments directly to the method. If date or time are not specified, the library queries for the most recent matching data. The method returns a result object containing the datetime of the downloaded forecast.

from ecmwf.opendata import Client

client = Client(source="ecmwf")

client.retrieve(
    time=0,
    type="fc",
    step=24,
    param=["2t", "msl"],
    target="data.grib2",
)

The Client.retrieve() method retrieves data from the server based on a request and writes it to a target file. You can provide the request as a dictionary of keyword/value pairs. You can specify a list of values for a given keyword to download multiple fields or steps at once.

Note: This package is optimized for downloading subsets of the dataset. For downloading very large portions of the dataset, downloading whole files locally may be more efficient.

from ecmwf.opendata import Client

client = Client(source="ecmwf")

request = {
    "time": 0,
    "type": "fc",
    "step": 24,
    "param": ["2t", "msl"],
}

client.retrieve(request, "data.grib2")

If you are accessing data from an Azure source, the client can automatically handle SAS (Shared Access Signature) token generation. This is enabled by default if source="azure".

To use a custom SAS token endpoint, provide sas_known_key and sas_custom_url during Client initialization.

client = Client(
    source="azure",
    use_sas_token=True,
    sas_known_key="my_custom_key",
    sas_custom_url="https://my-token-endpoint.com/api"
)

Requests are composed of keywords that identify which files to access and which parts of those files to download.

File Identification Keywords (Compulsory/Required):

• type: The type of data (defaults to fc).
• stream: The forecast system (e.g., oper, enfo, wave).
• date: The forecast start date (UTC).
• time: The forecast start time (UTC).
• step: The forecast time step in hours (or fcmonth for seasonal).

Data Filtering Keywords (Optional):

• param: Meteorological parameters (e.g., 2t, msl).
• levtype: Selection between single level and pressure levels.
• levelist: List of pressure levels.
• number: List of ensemble member numbers.

Once you have retrieved a field list using earthkit-data, you can use earthkit.plots.quickplot to visualize specific parameters. If your dataset contains multiple parameters, you can index into the field list (e.g., ds[1]) to plot a specific field.

import earthkit.plots

# Assuming ds is a fieldlist from earthkit.data
earthkit.plots.quickplot(ds[1])