ECMWF API Client

1.6.5 verified Fri May 01 auth: no python

Python client for ECMWF (European Centre for Medium-Range Weather Forecasts) web services API. Allows downloading meteorological data. Current version 1.6.5, actively maintained, with irregular releases.

pip install ecmwf-api-client

Common errors

error ecmwfapi.ECMWFService.ECMWFService.__init__() got an unexpected keyword argument 'url' ↓

cause ECMWFService does not accept 'url' parameter, only 'email' and 'key'.

fix

Use ECMWFDataServer for URL-based access, or omit 'url' for ECMWFService.

error ImportError: cannot import name 'ECMWFDataServer' from 'ecmwfapi' ↓

cause Possibly a corrupted installation or very old version; module name changed in v1.5.0?

fix

Reinstall: pip install --upgrade ecmwf-api-client. For older packages, import from ecmwf directly.

Warnings

deprecated ECMWFDataServer with URL 'https://api.ecmwf.int/v1' is deprecated; use 'https://api.ecmwf.int/v1' (still works) or migrate to new CDS API. ↓

fix Consider using the Climate Data Store (CDS) API client `cdsapi` for newer datasets.

gotcha Anonymous access (v1.6.0+) may silently succeed but returns limited data. If you expect full access, ensure key/email are provided. ↓

fix Always set ECMWF_API_KEY and ECMWF_EMAIL environment variables, or pass them explicitly.

breaking In v1.6.3, invalid API keys now fail fast instead of falling back to anonymous access. Code that relied on silent fallback will break. ↓

fix Ensure API keys are valid before making requests. If anonymous access is intended, do not set keys.

Imports

ECMWFDataServer
```
from ecmwfapi import ECMWFDataServer
```
Standard import path.
ECMWFService
```
from ecmwfapi import ECMWFService
```
For service-based access.

Quickstart

Downloads ERA5 data from the ECMWF API. Requires API key and email set in environment variables.

from ecmwfapi import ECMWFDataServer

server = ECMWFDataServer(url="https://api.ecmwf.int/v1", key=os.environ.get('ECMWF_API_KEY', ''), email=os.environ.get('ECMWF_EMAIL', ''))
server.retrieve({
    "class": "od",
    "dataset": "era5",
    "date": "2018-01-01/to/2018-01-02",
    "expver": "1",
    "levelist": "1",
    "levtype": "ml",
    "param": "130",
    "stream": "oper",
    "target": "output.grib",
    "time": "00:00:00/12:00:00",
    "type": "an",
    "grid": "1.0/1.0",
    "area": "50/-10/30/10",
    "format": "grib"
})