Hint

You can run this notebook in a live session with .

ECMWF API plugin for EODAG

This tutorial will show you how use eodag to download data from ECWMF using EcmwfApi eodag plugin. The API plugin and this tutorial have been developed in the context of DOMINO-X.

from eodag import EODataAccessGateway, setup_logging

setup_logging(1)  # 0: nothing, 1: only progress bars, 2: INFO, 3: DEBUG
dag = EODataAccessGateway()
dag.set_preferred_provider("ecmwf")

Search (build download request) from an existing collection:

In this example, we will request data from TIGGE public dataset, using a collection already configured in eodag (TIGGE_CF_SFC) or using a custom request to access the same data.

Retrieval request can be customized from ecmwf web ui on https://apps.ecmwf.int/datasets/data/tigge.

For performance purpose, we request a single param (total cloud cover, tcc) to the request as TIGGE_CF_SFC is configured to ask for all available param values. See ecmwf availables parameters. You can add more MARS keywords, that will overwrite default values configured for TIGGE_CF_SFC collection.

products_from_collection = dag.search(
    geom=[-60, 30, -130, 70],
    start="2021-11-01",
    end="2021-11-02",
    collection="TIGGE_CF_SFC",
    **{
      "ecmwf:class": "ti",
      "ecmwf:dataset": "tigge",
      "ecmwf:expver": "prod",
      "ecmwf:type": "cf",
      "ecmwf:levtype": "sfc",
      "ecmwf:origin": "ecmwf",
      "ecmwf:grid": "0.5/0.5",
      "ecmwf:param": "tcc",
      "ecmwf:step": "0",
      "ecmwf:time": "00:00",
      "ecmwf:target": "output"
    }
)
products_from_collection

SearchResult (1)

0  EOProduct(id=TIGGE_CF_SFC_ORDERABLE_2717adc865d5b21469be9c6f68dc528951d3877d, provider=ecmwf) EOProduct provider: 'ecmwf', collection: 'TIGGE_CF_SFC', properties["id"]: 'TIGGE_CF_SFC_ORDERABLE_2717adc865d5b21469be9c6f68dc528951d3877d', properties["start_datetime"]: '2021-11-01T00:00:00.000Z', properties["end_datetime"]: '2021-11-02T00:00:00.000Z', properties: (20) { end_datetime: '2021-11-02T00:00:00.000Z', id: 'TIGGE_CF_SFC_ORDERABLE_2717adc865d5b21469be9c6f68dc528951d3877d', qs: { 'area': '70.0/-130.0/30.0/-60.0' , 'class': 'ti' , 'dataset': 'tigge' , 'date': '2021-11-01/to/2021-11-01' , 'expver': 'prod' , 'grid': '0.5/0.5' , 'levtype': 'sfc' , 'origin': 'ecmwf' , 'param': 'tcc' , 'step': '0' , 'target': 'output' , 'time': '00:00' , 'type': 'cf' }, start_datetime: '2021-11-01T00:00:00.000Z', title: 'TIGGE_CF_SFC_ORDERABLE_2717adc865d5b21469be9c6f68dc528951d3877d', ecmwf:class: 'ti', ecmwf:dataset: 'tigge', ecmwf:date: '2021-11-01/to/2021-11-01', ecmwf:expver: 'prod', ecmwf:grid: '0.5/0.5', ecmwf:levtype: 'sfc', ecmwf:origin: 'ecmwf', ecmwf:param: 'tcc', ecmwf:step: '0', ecmwf:target: 'output', ecmwf:time: '00:00', ecmwf:type: 'cf', eodag:default_geometry: 'POLYGON((180 -90, 180 90, -180 90, -180 -90, 180 -90))', eodag:download_link: 'https://apps.ecmwf.int/datasets/data/tigge?{"area": "70.0/-130.0/30.0/-60.0", "class": "ti", "dataset": "tigge", "date": "2021-11-01/to/2021-11-01", "expver": "prod", "grid": "0.5/0.5", "levtype": "sfc", "origin": "ecmwf", "param": "tcc", "step": "0", "target": "output", "time": "00:00", "type": "cf"}', order:status: 'succeeded', } assets: (0) geometry

Note

You can also directly use MARS parameters as is through EODAG search API and replace collection with the desired dataset (tigge is this case)

Send product retrieval request and load it as an xarray.DataArray

• download performed using ECMWF credentials set in ~/.config/eodag/eodag.yml as for other EO providers:

ecmwf:
    priority:
    api:
        output_dir: /my/path/to/data/eodag_data
        credentials:
            username: john.doe@csgroup.eu
            password: my-ecmwf-api-access-key

• you can check your request status from https://apps.ecmwf.int/webmars/joblist/

• See ECMWF guidelines if request is queued for a long time

# Get XarrayDict
xd = products_from_collection[0].to_xarray()
xd

XarrayDict (1)

'grib':  xarray.Dataset (latitude: 81, longitude: 141)  Size: 48kB <xarray.Dataset> Size: 48kB Dimensions: (latitude: 81, longitude: 141) Coordinates: number int64 8B ... time datetime64[ns] 8B ... step timedelta64[ns] 8B ... entireAtmosphere float64 8B ... * latitude (latitude) float64 648B 70.0 69.5 69.0 ... 31.0 30.5 30.0 * longitude (longitude) float64 1kB 230.0 230.5 231.0 ... 299.5 300.0 valid_time datetime64[ns] 8B ... Data variables: tcc (latitude, longitude) float32 46kB ... Attributes: (12/27) GRIB_edition: 2 GRIB_centre: ecmf GRIB_centreDescription: European Centre for Medium-Range Weather Forecasts GRIB_subCentre: 0 Conventions: CF-1.7 institution: European Centre for Medium-Range Weather Forecasts ... ... ecmwf:target: output ecmwf:time: 00:00 ecmwf:type: cf eodag:default_geometry: POLYGON((180 -90, 180 90, -180 90, -180 -90, 180... eodag:download_link: https://apps.ecmwf.int/datasets/data/tigge?{"are... order:status: succeeded xarray.Dataset Dimensions: latitude: 81 longitude: 141 Coordinates: (7) number () int64 ... long_name : ensemble member numerical id units : 1 standard_name : realization [1 values with dtype=int64] time () datetime64[ns] ... long_name : initial time of forecast standard_name : forecast_reference_time [1 values with dtype=datetime64[ns]] step () timedelta64[ns] ... long_name : time since forecast_reference_time standard_name : forecast_period [1 values with dtype=timedelta64[ns]] entireAtmosphere () float64 ... long_name : original GRIB coordinate for key: level(entireAtmosphere) units : 1 [1 values with dtype=float64] latitude (latitude) float64 70.0 69.5 69.0 ... 31.0 30.5 30.0 units : degrees_north standard_name : latitude long_name : latitude stored_direction : decreasing array([70. , 69.5, 69. , 68.5, 68. , 67.5, 67. , 66.5, 66. , 65.5, 65. , 64.5, 64. , 63.5, 63. , 62.5, 62. , 61.5, 61. , 60.5, 60. , 59.5, 59. , 58.5, 58. , 57.5, 57. , 56.5, 56. , 55.5, 55. , 54.5, 54. , 53.5, 53. , 52.5, 52. , 51.5, 51. , 50.5, 50. , 49.5, 49. , 48.5, 48. , 47.5, 47. , 46.5, 46. , 45.5, 45. , 44.5, 44. , 43.5, 43. , 42.5, 42. , 41.5, 41. , 40.5, 40. , 39.5, 39. , 38.5, 38. , 37.5, 37. , 36.5, 36. , 35.5, 35. , 34.5, 34. , 33.5, 33. , 32.5, 32. , 31.5, 31. , 30.5, 30. ]) longitude (longitude) float64 230.0 230.5 231.0 ... 299.5 300.0 units : degrees_east standard_name : longitude long_name : longitude array([230. , 230.5, 231. , 231.5, 232. , 232.5, 233. , 233.5, 234. , 234.5, 235. , 235.5, 236. , 236.5, 237. , 237.5, 238. , 238.5, 239. , 239.5, 240. , 240.5, 241. , 241.5, 242. , 242.5, 243. , 243.5, 244. , 244.5, 245. , 245.5, 246. , 246.5, 247. , 247.5, 248. , 248.5, 249. , 249.5, 250. , 250.5, 251. , 251.5, 252. , 252.5, 253. , 253.5, 254. , 254.5, 255. , 255.5, 256. , 256.5, 257. , 257.5, 258. , 258.5, 259. , 259.5, 260. , 260.5, 261. , 261.5, 262. , 262.5, 263. , 263.5, 264. , 264.5, 265. , 265.5, 266. , 266.5, 267. , 267.5, 268. , 268.5, 269. , 269.5, 270. , 270.5, 271. , 271.5, 272. , 272.5, 273. , 273.5, 274. , 274.5, 275. , 275.5, 276. , 276.5, 277. , 277.5, 278. , 278.5, 279. , 279.5, 280. , 280.5, 281. , 281.5, 282. , 282.5, 283. , 283.5, 284. , 284.5, 285. , 285.5, 286. , 286.5, 287. , 287.5, 288. , 288.5, 289. , 289.5, 290. , 290.5, 291. , 291.5, 292. , 292.5, 293. , 293.5, 294. , 294.5, 295. , 295.5, 296. , 296.5, 297. , 297.5, 298. , 298.5, 299. , 299.5, 300. ]) valid_time () datetime64[ns] ... standard_name : time long_name : time [1 values with dtype=datetime64[ns]] Data variables: (1) tcc (latitude, longitude) float32 ... GRIB_paramId : 228164 GRIB_dataType : cf GRIB_numberOfPoints : 11421 GRIB_typeOfLevel : entireAtmosphere GRIB_stepUnits : 1 GRIB_stepType : instant GRIB_gridType : regular_ll GRIB_uvRelativeToGrid : 0 GRIB_NV : 0 GRIB_Nx : 141 GRIB_Ny : 81 GRIB_cfName : unknown GRIB_cfVarName : tcc GRIB_gridDefinitionDescription : Latitude/longitude GRIB_iDirectionIncrementInDegrees : 0.5 GRIB_iScansNegatively : 0 GRIB_jDirectionIncrementInDegrees : 0.5 GRIB_jPointsAreConsecutive : 0 GRIB_jScansPositively : 0 GRIB_latitudeOfFirstGridPointInDegrees : 70.0 GRIB_latitudeOfLastGridPointInDegrees : 30.0 GRIB_longitudeOfFirstGridPointInDegrees : 230.0 GRIB_longitudeOfLastGridPointInDegrees : 300.0 GRIB_missingValue : 3.4028234663852886e+38 GRIB_name : Total Cloud Cover GRIB_shortName : tcc GRIB_totalNumber : 51 GRIB_units : % long_name : Total Cloud Cover units : % standard_name : unknown [11421 values with dtype=float32] Indexes: (2) latitude PandasIndex PandasIndex(Index([70.0, 69.5, 69.0, 68.5, 68.0, 67.5, 67.0, 66.5, 66.0, 65.5, 65.0, 64.5, 64.0, 63.5, 63.0, 62.5, 62.0, 61.5, 61.0, 60.5, 60.0, 59.5, 59.0, 58.5, 58.0, 57.5, 57.0, 56.5, 56.0, 55.5, 55.0, 54.5, 54.0, 53.5, 53.0, 52.5, 52.0, 51.5, 51.0, 50.5, 50.0, 49.5, 49.0, 48.5, 48.0, 47.5, 47.0, 46.5, 46.0, 45.5, 45.0, 44.5, 44.0, 43.5, 43.0, 42.5, 42.0, 41.5, 41.0, 40.5, 40.0, 39.5, 39.0, 38.5, 38.0, 37.5, 37.0, 36.5, 36.0, 35.5, 35.0, 34.5, 34.0, 33.5, 33.0, 32.5, 32.0, 31.5, 31.0, 30.5, 30.0], dtype='float64', name='latitude')) longitude PandasIndex PandasIndex(Index([230.0, 230.5, 231.0, 231.5, 232.0, 232.5, 233.0, 233.5, 234.0, 234.5, ... 295.5, 296.0, 296.5, 297.0, 297.5, 298.0, 298.5, 299.0, 299.5, 300.0], dtype='float64', name='longitude', length=141)) Attributes: (27) GRIB_edition : 2 GRIB_centre : ecmf GRIB_centreDescription : European Centre for Medium-Range Weather Forecasts GRIB_subCentre : 0 Conventions : CF-1.7 institution : European Centre for Medium-Range Weather Forecasts history : 2025-10-19T19:31 GRIB to CDM+CF via cfgrib-0.9.15.0/ecCodes-2.39.2 with {"source": "../../../../../../../tmp/TIGGE_CF_SFC_ORDERABLE_2717adc865d5b21469be9c6f68dc528951d3877d/TIGGE_CF_SFC_ORDERABLE_2717adc865d5b21469be9c6f68dc528951d3877d.grib", "filter_by_keys": {}, "encode_cf": ["parameter", "time", "geography", "vertical"]} end_datetime : 2021-11-02T00:00:00.000Z id : TIGGE_CF_SFC_ORDERABLE_2717adc865d5b21469be9c6f68dc528951d3877d qs : {'area': '70.0/-130.0/30.0/-60.0', 'class': 'ti', 'dataset': 'tigge', 'date': '2021-11-01/to/2021-11-01', 'expver': 'prod', 'grid': '0.5/0.5', 'levtype': 'sfc', 'origin': 'ecmwf', 'param': 'tcc', 'step': '0', 'target': 'output', 'time': '00:00', 'type': 'cf'} start_datetime : 2021-11-01T00:00:00.000Z title : TIGGE_CF_SFC_ORDERABLE_2717adc865d5b21469be9c6f68dc528951d3877d ecmwf:class : ti ecmwf:dataset : tigge ecmwf:date : 2021-11-01/to/2021-11-01 ecmwf:expver : prod ecmwf:grid : 0.5/0.5 ecmwf:levtype : sfc ecmwf:origin : ecmwf ecmwf:param : tcc ecmwf:step : 0 ecmwf:target : output ecmwf:time : 00:00 ecmwf:type : cf eodag:default_geometry : POLYGON((180 -90, 180 90, -180 90, -180 -90, 180 -90)) eodag:download_link : https://apps.ecmwf.int/datasets/data/tigge?{"area": "70.0/-130.0/30.0/-60.0", "class": "ti", "dataset": "tigge", "date": "2021-11-01/to/2021-11-01", "expver": "prod", "grid": "0.5/0.5", "levtype": "sfc", "origin": "ecmwf", "param": "tcc", "step": "0", "target": "output", "time": "00:00", "type": "cf"} order:status : succeeded

# DataArray from XarrayDict first value
da = next(iter(xd.values())).tcc
da

<xarray.DataArray 'tcc' (latitude: 81, longitude: 141)> Size: 46kB
[11421 values with dtype=float32]
Coordinates:
    number            int64 8B ...
    time              datetime64[ns] 8B ...
    step              timedelta64[ns] 8B ...
    entireAtmosphere  float64 8B ...
  * latitude          (latitude) float64 648B 70.0 69.5 69.0 ... 31.0 30.5 30.0
  * longitude         (longitude) float64 1kB 230.0 230.5 231.0 ... 299.5 300.0
    valid_time        datetime64[ns] 8B ...
Attributes: (12/31)
    GRIB_paramId:                             228164
    GRIB_dataType:                            cf
    GRIB_numberOfPoints:                      11421
    GRIB_typeOfLevel:                         entireAtmosphere
    GRIB_stepUnits:                           1
    GRIB_stepType:                            instant
    ...                                       ...
    GRIB_shortName:                           tcc
    GRIB_totalNumber:                         51
    GRIB_units:                               %
    long_name:                                Total Cloud Cover
    units:                                    %
    standard_name:                            unknown

xarray.DataArray

'tcc'

• latitude: 81
• longitude: 141

• ...

  [11421 values with dtype=float32]

• Coordinates: (7)
  • number
    ()
    int64
    ...

    long_name :

    ensemble member numerical id

    units :

    1

    standard_name :

    realization

    [1 values with dtype=int64]

  • time
    ()
    datetime64[ns]
    ...

    long_name :

    initial time of forecast

    standard_name :

    forecast_reference_time

    [1 values with dtype=datetime64[ns]]

  • step
    ()
    timedelta64[ns]
    ...

    long_name :

    time since forecast_reference_time

    standard_name :

    forecast_period

    [1 values with dtype=timedelta64[ns]]

  • entireAtmosphere
    ()
    float64
    ...

    long_name :

    original GRIB coordinate for key: level(entireAtmosphere)

    units :

    1

    [1 values with dtype=float64]

  • latitude
    (latitude)
    float64
    70.0 69.5 69.0 ... 31.0 30.5 30.0

    units :

    degrees_north

    standard_name :

    latitude

    long_name :

    latitude

    stored_direction :

    decreasing

    array([70. , 69.5, 69. , 68.5, 68. , 67.5, 67. , 66.5, 66. , 65.5, 65. , 64.5,
           64. , 63.5, 63. , 62.5, 62. , 61.5, 61. , 60.5, 60. , 59.5, 59. , 58.5,
           58. , 57.5, 57. , 56.5, 56. , 55.5, 55. , 54.5, 54. , 53.5, 53. , 52.5,
           52. , 51.5, 51. , 50.5, 50. , 49.5, 49. , 48.5, 48. , 47.5, 47. , 46.5,
           46. , 45.5, 45. , 44.5, 44. , 43.5, 43. , 42.5, 42. , 41.5, 41. , 40.5,
           40. , 39.5, 39. , 38.5, 38. , 37.5, 37. , 36.5, 36. , 35.5, 35. , 34.5,
           34. , 33.5, 33. , 32.5, 32. , 31.5, 31. , 30.5, 30. ])

  • longitude
    (longitude)
    float64
    230.0 230.5 231.0 ... 299.5 300.0

    units :

    degrees_east

    standard_name :

    longitude

    long_name :

    longitude

    array([230. , 230.5, 231. , 231.5, 232. , 232.5, 233. , 233.5, 234. , 234.5,
           235. , 235.5, 236. , 236.5, 237. , 237.5, 238. , 238.5, 239. , 239.5,
           240. , 240.5, 241. , 241.5, 242. , 242.5, 243. , 243.5, 244. , 244.5,
           245. , 245.5, 246. , 246.5, 247. , 247.5, 248. , 248.5, 249. , 249.5,
           250. , 250.5, 251. , 251.5, 252. , 252.5, 253. , 253.5, 254. , 254.5,
           255. , 255.5, 256. , 256.5, 257. , 257.5, 258. , 258.5, 259. , 259.5,
           260. , 260.5, 261. , 261.5, 262. , 262.5, 263. , 263.5, 264. , 264.5,
           265. , 265.5, 266. , 266.5, 267. , 267.5, 268. , 268.5, 269. , 269.5,
           270. , 270.5, 271. , 271.5, 272. , 272.5, 273. , 273.5, 274. , 274.5,
           275. , 275.5, 276. , 276.5, 277. , 277.5, 278. , 278.5, 279. , 279.5,
           280. , 280.5, 281. , 281.5, 282. , 282.5, 283. , 283.5, 284. , 284.5,
           285. , 285.5, 286. , 286.5, 287. , 287.5, 288. , 288.5, 289. , 289.5,
           290. , 290.5, 291. , 291.5, 292. , 292.5, 293. , 293.5, 294. , 294.5,
           295. , 295.5, 296. , 296.5, 297. , 297.5, 298. , 298.5, 299. , 299.5,
           300. ])

  • valid_time
    ()
    datetime64[ns]
    ...

    standard_name :

    time

    long_name :

    time

    [1 values with dtype=datetime64[ns]]

• Indexes: (2)
  • latitude
    PandasIndex

    PandasIndex(Index([70.0, 69.5, 69.0, 68.5, 68.0, 67.5, 67.0, 66.5, 66.0, 65.5, 65.0, 64.5,
           64.0, 63.5, 63.0, 62.5, 62.0, 61.5, 61.0, 60.5, 60.0, 59.5, 59.0, 58.5,
           58.0, 57.5, 57.0, 56.5, 56.0, 55.5, 55.0, 54.5, 54.0, 53.5, 53.0, 52.5,
           52.0, 51.5, 51.0, 50.5, 50.0, 49.5, 49.0, 48.5, 48.0, 47.5, 47.0, 46.5,
           46.0, 45.5, 45.0, 44.5, 44.0, 43.5, 43.0, 42.5, 42.0, 41.5, 41.0, 40.5,
           40.0, 39.5, 39.0, 38.5, 38.0, 37.5, 37.0, 36.5, 36.0, 35.5, 35.0, 34.5,
           34.0, 33.5, 33.0, 32.5, 32.0, 31.5, 31.0, 30.5, 30.0],
          dtype='float64', name='latitude'))

  • longitude
    PandasIndex

    PandasIndex(Index([230.0, 230.5, 231.0, 231.5, 232.0, 232.5, 233.0, 233.5, 234.0, 234.5,
           ...
           295.5, 296.0, 296.5, 297.0, 297.5, 298.0, 298.5, 299.0, 299.5, 300.0],
          dtype='float64', name='longitude', length=141))

• Attributes: (31)

  GRIB_paramId :

  228164

  GRIB_dataType :

  cf

  GRIB_numberOfPoints :

  11421

  GRIB_typeOfLevel :

  entireAtmosphere

  GRIB_stepUnits :

  1

  GRIB_stepType :

  instant

  GRIB_gridType :

  regular_ll

  GRIB_uvRelativeToGrid :

  0

  GRIB_NV :

  0

  GRIB_Nx :

  141

  GRIB_Ny :

  81

  GRIB_cfName :

  unknown

  GRIB_cfVarName :

  tcc

  GRIB_gridDefinitionDescription :

  Latitude/longitude

  GRIB_iDirectionIncrementInDegrees :

  0.5

  GRIB_iScansNegatively :

  0

  GRIB_jDirectionIncrementInDegrees :

  0.5

  GRIB_jPointsAreConsecutive :

  0

  GRIB_jScansPositively :

  0

  GRIB_latitudeOfFirstGridPointInDegrees :

  70.0

  GRIB_latitudeOfLastGridPointInDegrees :

  30.0

  GRIB_longitudeOfFirstGridPointInDegrees :

  230.0

  GRIB_longitudeOfLastGridPointInDegrees :

  300.0

  GRIB_missingValue :

  3.4028234663852886e+38

  GRIB_name :

  Total Cloud Cover

  GRIB_shortName :

  tcc

  GRIB_totalNumber :

  51

  GRIB_units :

  %

  long_name :

  Total Cloud Cover

  units :

  %

  standard_name :

  unknown

Plot using cartopy

import matplotlib.pyplot as plt
import cartopy.crs as ccrs

ax = plt.axes(projection=ccrs.Orthographic(-80, 35))
ax.coastlines()
ax.gridlines(draw_labels=True)
da.plot.contourf(ax=ax, transform=ccrs.PlateCarree())

<cartopy.mpl.contour.GeoContourSet at 0x7f8c3858d160>