pvlib.iotools.get_ecmwf_macc(filename, params, start, end, lookup_params=True, server=None, target=<function _ecmwf>)[source]#

Download data from ECMWF MACC Reanalysis API.

  • filename (str) – full path of file where to save data, .nc appended if not given

  • params (str or sequence of str) – keynames of parameter[s] to download

  • start (datetime.datetime or datetime.date) – UTC date

  • end (datetime.datetime or datetime.date) – UTC date

  • lookup_params (bool, default True) – optional flag, if False, then codes are already formatted

  • server (ecmwfapi.api.ECMWFDataServer) – optionally provide a server object, default is None

  • target (callable) – optional function that calls server.retrieve to pass to thread


t (thread) – a thread object, use it to check status by calling t.is_alive()


To download data from ECMWF requires the API client and a registration key. Please read the documentation in Access ECMWF Public Datasets. Follow the instructions in step 4 and save the ECMWF registration key as $HOME/.ecmwfapirc or set ECMWF_API_KEY as the path to the key.

This function returns a daemon thread that runs in the background. Exiting Python will kill this thread, however this thread will not block the main thread or other threads. This thread will terminate when the file is downloaded or if the thread raises an unhandled exception. You may submit multiple requests simultaneously to break up large downloads. You can also check the status and retrieve downloads online at http://apps.ecmwf.int/webmars/joblist/. This is useful if you kill the thread. Downloads expire after 24 hours.


Your request may be queued online for an hour or more before it begins to download

Precipitable water \(P_{wat}\) is equivalent to the total column of water vapor (TCWV), but the units given by ECMWF MACC Reanalysis are kg/m^2 at STP (1-atm, 25-C). Divide by ten to convert to centimeters of precipitable water:

\[P_{wat} \left( \text{cm} \right) = TCWV \left( \frac{\text{kg}}{\text{m}^2} \right) \frac{100 \frac{\text{cm}}{\text{m}}} {1000 \frac{\text{kg}}{\text{m}^3}}\]

The keynames available for the params argument are given by pvlib.iotools.ecmwf_macc.PARAMS which maps the keys to codes used in the API. The following keynames are available:




total column water vapor in kg/m^2 at STP


aerosol optical depth measured at 550-nm


aerosol optical depth measured at 469-nm


aerosol optical depth measured at 670-nm


aerosol optical depth measured at 865-nm


aerosol optical depth measured at 1240-nm

If lookup_params is False then params must contain the codes preformatted according to the ECMWF MACC Reanalysis API. This is useful if you want to retrieve codes that are not mapped in pvlib.iotools.ecmwf_macc.PARAMS.

Specify a custom target function to modify how the ECMWF API function server.retrieve is called. The target function must have the following signature in which the parameter definitions are similar to pvlib.iotools.get_ecmwf_macc().

target(server, startdate, enddate, params, filename) -> None


Retrieve the AOD measured at 550-nm and the total column of water vapor for November 1, 2012.

>>> from datetime import date
>>> from pvlib.iotools import get_ecmwf_macc
>>> filename = 'aod_tcwv_20121101.nc'  # .nc extension added if missing
>>> params = ('aod550', 'tcwv')
>>> start = end = date(2012, 11, 1)
>>> t = get_ecmwf_macc(filename, params, start, end)
>>> t.is_alive()