- Created by XCristian XSimarro2, last modified by Roberto Cuccu on Sep 01, 2023
This Service will allow authorised users to retrieve and list MARS data from outside the ECMWF facilities. Users within ECMWF Member and Co-operating States may contact their Computing Representative to obtain access to MARS. All other users may request a username and password, following these instructions.
In this page you will find the step-by-step guide to install the ECMWF Web API client and create your own MARS Requests. We strongly recommend you that you get familiar with MARS.
Information
For those used to the MARS system, it is worth noting that the client that you will install in your system is a Web API service interface that forwards the request to our systems and expects a single output file. It has no knowledge of internal ECMWF libraries such as MIR or ecCodes, these operations are performed in our internal servers. Therefore, not all the functionality of the full MARS client is available, like multi-target, compute, etc...
This method is only supported on UNIX systems. It requires Python.
(Optional) To follow this guide, we recommend you to have a directory in your $HOME space called "mars".
mkdir -p ~/mars/bin mkdir -p ~/mars/lib
Download the mars python script: mars. You have to give execution permission to the file and put it in a location in your PATH.
If the file has been downloaded to ~/mars/bin, you have to execute:
chmod +x ~/mars/bin/mars export PATH=~/mars/bin/:$PATH
The ecmwf-api-client library was added to the Python Package Index (PYPI):
Install via pip with:
pip install ecmwf-api-client
If you do not have admin privileges you can always install the client in your user space:
pip install --user ecmwf-api-client
Alternatively, if you have Anaconda installed you can install the Web API Python client library doing:
conda install -c conda-forge ecmwf-api-client
If you have Anaconda installed you can install the Web API Python client library doing:
conda install -c conda-forge ecmwf-api-client
Alternatively, you can first install Python (and pip) on your Windows environment.
- Download windows installer exe from Python.org download page
- Run the exe.
- Screen will be shown to chose the installation option.
- Uncheck "install for all user" option.
- Go for the custom installation.
- On next screen specify the directory path for which your user have full access on the computer (take a note of this as you will need it to set the environment variables).
- Uncheck "create shortcuts for installed application" option.
- Make sure "Add python to environment variable" option is Unchecked .
- Complete the installation.
Then add the installation and Script folder path in PATH using set (temporary) or setx (permanent) in a Command Prompt window. This is to make sure that your computer knows where to find the Python interpreter. To do this you will have to modify a setting called PATH, which is a list of directories where Windows will look for programs. Further details and examples are available here. You may choose also to set your environment variables into a batch file (e.g. set-env.bat which you will need to run from the Command Prompt.
@echo off
set PY_HOME=C:\...\python37
set PATH=%PY_HOME%;%PY_HOME%\Scripts;%PATH%
You can now install it via pip (see instructions above).
For languages other than Python please see Web-API Downloads
You can also try visiting https://api.ecmwf.int/v1/key/ to retrieve your credentials.
Note that the key expires in 1 year. You will receive an email to the registered email address 1 month before the expiration date with the renewal instructions.
Example script
Retrieval of sea surface temperature for the first 10 days of May 2002, all synoptic times. It retrieves 40 fields.
retrieve, class = od, stream = oper, expver = 1, date = 20020501/to/20020510, time = 00/06/12/18, type = an, levtype = sfc, param = sea surface temperature, target = "sst.grib"
Save this script as test.req and execute:
mars test.req
The command should generate a sst.grib file containing the retrieved 40 fields in GRIB format.
You can use ECMWFService Python class to execute a retrieve command:
server = ECMWFService("mars") server.execute({ "python":"query" }, "target") # Alternatively the function execute can also accept a text variable with the request server.execute(req,target)
Example:
#!/usr/bin/env python from ecmwfapi import ECMWFService server = ECMWFService("mars") server.execute( { "class": "od", "date": "20150101", "expver": "1", "levtype": "sfc", "param": "167.128", "step": "0/to/240/by/12", "stream": "oper", "time": "00", "type": "fc" }, "target.grib")
To check the Data availability you should have Access to the MARS Catalogue. Please note that the MARS catalogue is a super-set of the Archive catalogue.
MARS Catalogue (restricted to authorised users)
you will view all the experiments that are available from our archive. We strongly recommend you to to navigate through MARS Catalogue to become familiar with the availability of our archive. You may select a class and start navigate trough the contents.
Please take into account some considerations about the content:
- Different class and stream include different parameters, times, and steps
- In each class not all the parameters are available from all steps
- In each class and stream not all the steps are available from all times
The web-application above will help you to check and understand the availability. For any kind of selections the system will update the attributes in a dynamic way to reflect the current availability. (i.e. if you change the steps some parameters will be added or removed).
Tip
We encourage users to use the " View MARS request " feature once the selection has been done.
You can also use list action with output=cost keyword to see the available data and its cost without need to retrieve it. This is useful to check the amount of data and number of tapes that your request will need to access. If your request takes longer than expected, it is a good practice to check its cost.
list, class = od, stream = oper, expver = 1, date = 20020501/to/20020510, time = 00/06/12/18, type = an, levtype = sfc, param = sea surface temperature, output = cost, target = "sst.list"
#!/usr/bin/env python from ecmwfapi import ECMWFService server = ECMWFService("mars") req = ''' list, class = od, stream = oper, expver = 1, date = 20020501/to/20020510, time = 00/06/12/18, type = an, levtype = sfc, param = sea surface temperature, output = cost ''' server.execute(req, "sst.list")
This would produce something like:
size=21599920; number_of_fields=40; online_size=21599920; off_line_size=0; number_of_tape_files=0; number_of_disk_files=1; number_of_online_fields=40; number_of_offline_fields=0; number_of_tapes=0;
Indicating that the size of this request will be 20.59 Mb (output is in Kb) and that it is fully located in the online disk (no need to access any tape).
Bear in mind that the maximum value of number_of_tapes recommended is 1 tape per request and should not exceed 3. Otherwise we strongly encourage you to split it in several different requests iterating by date.
If you do not set the "output=cost" keyword on the list action, the output will show you information about the type of requests and the entries:
class = od expver = 1 file[0] = hpss:/mars/prod/od/o/oper/an/sfc/marsodoper/1/an/20020501/sfc/126665.20031108.113424 id = 126665 levtype = sfc month = 200205 stream = oper type = an year = 2002 date file length missing offset param time 2002-05-01 0 539998 . 4729126 34.128 00:00:00 2002-05-01 0 539998 . 37233582 34.128 06:00:00 2002-05-01 0 539998 . 69738038 34.128 12:00:00 2002-05-01 0 539998 . 102242494 34.128 18:00:00 2002-05-02 0 539998 . 134746950 34.128 00:00:00 2002-05-02 0 539998 . 167251406 34.128 06:00:00 2002-05-02 0 539998 . 199755862 34.128 12:00:00 2002-05-02 0 539998 . 232260318 34.128 18:00:00 2002-05-03 0 539998 . 264764774 34.128 00:00:00 2002-05-03 0 539998 . 297269230 34.128 06:00:00 2002-05-03 0 539998 . 329773686 34.128 12:00:00 2002-05-03 0 539998 . 362278142 34.128 18:00:00 2002-05-04 0 539998 . 394782598 34.128 00:00:00 2002-05-04 0 539998 . 427287054 34.128 06:00:00 2002-05-04 0 539998 . 459791510 34.128 12:00:00 2002-05-04 0 539998 . 492295966 34.128 18:00:00 2002-05-05 0 539998 . 524800422 34.128 00:00:00 2002-05-05 0 539998 . 557304878 34.128 06:00:00 2002-05-05 0 539998 . 589809334 34.128 12:00:00 2002-05-05 0 539998 . 622313790 34.128 18:00:00 2002-05-06 0 539998 . 654818246 34.128 00:00:00 2002-05-06 0 539998 . 687322702 34.128 06:00:00 2002-05-06 0 539998 . 719827158 34.128 12:00:00 2002-05-06 0 539998 . 752331614 34.128 18:00:00 2002-05-07 0 539998 . 784836070 34.128 00:00:00 2002-05-07 0 539998 . 817340526 34.128 06:00:00 2002-05-07 0 539998 . 849844982 34.128 12:00:00 2002-05-07 0 539998 . 882349438 34.128 18:00:00 2002-05-08 0 539998 . 914853894 34.128 00:00:00 2002-05-08 0 539998 . 947358350 34.128 06:00:00 2002-05-08 0 539998 . 979862806 34.128 12:00:00 2002-05-08 0 539998 . 1012367262 34.128 18:00:00 2002-05-09 0 539998 . 1044871718 34.128 00:00:00 2002-05-09 0 539998 . 1077376174 34.128 06:00:00 2002-05-09 0 539998 . 1109880630 34.128 12:00:00 2002-05-09 0 539998 . 1142385086 34.128 18:00:00 2002-05-10 0 539998 . 1174889542 34.128 00:00:00 2002-05-10 0 539998 . 1207393998 34.128 06:00:00 2002-05-10 0 539998 . 1239898454 34.128 12:00:00 2002-05-10 0 539998 . 1272402910 34.128 18:00:00 Grand Total: ============ Entries : 40 Total : 21,599,920 (20.5993 Mbytes)
Spend some time to understand how it works, make some selections try to execute the MARS scripts.
Retrieval of snow depth from the ERA-40 archive for November 1993, for all analysis base times. It retrieves 120 fields. See in MARS Catalogue
retrieve, class = e4, stream = oper, expver = 1, date = 19931101/to/19931130, time = 00/06/12/18, type = an, levtype = sfc, param = sd, repres = gg, target = "era40.199311.sd"
Retrieval of sea surface temperature for the first 10 days of May 2002, all synoptic times. It retrieves 40 fields. See in MARS Catalogue
retrieve, class = od, stream = oper, expver = 1, date = 20020501/to/20020510, time = 00/06/12/18, type = an, levtype = sfc, param = sea surface temperature, target = "sst"
Retrieval of surface temperature an 10m wind components (U and V), 20 first members of the EPS for 2nd January 2001 for time-steps 12, 36 and 60. It retrieves 180 fields. See in MARS Catalogue
retrieve, class = od, stream = enfo, expver = 1, date = 20010102, time = 12, step = 12/36/60, type = pf, levtype = sfc, param = st/10u/10v, number = 1/to/20, target = "perturbed.sfc"
Retrieval of snow depth from the ERA-Interim archive for December 2007, for all analysis base times. It retrieves 124 fields. See in MARS Catalogue
retrieve, class = ei, stream = oper, expver = 1, date = 20071201/to/20071231 time = 00/06/12/18, type = an, levtype = sfc, param = sd, target = "era-int.200712.sd"
You can find more advanced examples here: MARS example requests
We strongly suggest users to split their requests by date e.g. one month at a time.
If you want to get big chunks of data, please have a look to the Retrieval efficiency page.
See Brief MARS request syntax page.
Training material (slides, pdf): MARS introduction and basic concepts
Related articles
There is no content with the specified labels
Blog Posts
-
Blog: Decommissioning of ECMWF Public Datasets service
created by
Mar 02, 2023
-
Blog: ERA5 access migrated to the Climate Data Store (CDS)
created by
Mar 05, 2019
-
Blog: IMPORTANT New interpolation software: MIR
created by
Jan 29, 2019
-
Blog: New Public Dataset: CERA-SAT Monthly
created by
Oct 15, 2018
-
Blog: ERA5 and C3S users should migrate they work to CDS
created by
Aug 02, 2018
-
Blog: Change in the Web API behaviour: expected fields vs. retrieved fields
created by
Feb 26, 2018
-
Blog: New Public Dataset: CERA-SAT
created by
Dec 08, 2017
-
Blog: New models added on Public Dataset UERRA
created by
Nov 23, 2017
-
Blog: New Public Dataset: CAMS Reanalysis
created by
Nov 13, 2017
-
Blog: Limit the period of a request via the Web User Interface
created by
Nov 10, 2017
-
Blog: New Public Dataset: C3S Seasonal forecasts
created by
Nov 02, 2017
-
Blog: New Public Dataset: CERA-20C Observation Feedback
created by
Oct 03, 2017
-
Blog: Web-API client version 1.5.0 released
created by
Sep 20, 2017
-
Blog: New Public Dataset: ERA5 reanalysis
created by
Aug 03, 2017
-
Blog: New Public Dataset: CAMS climate forcing
created by
Jun 02, 2017
-
Blog: New Public Dataset: UERRA Harmonie and UM-4dvar
created by
May 25, 2017
-
Blog: New Public Dataset: Year Of Polar Prediction (YOPP)
created by
May 10, 2017
-
Blog: New Public Dataset: Global ECMWF Fire Forecasting model (GEFF)
created by
Feb 27, 2017
-
Blog: New Public Dataset: CERA-20C daily
created by
Jan 30, 2017
-
Blog: New Public Dataset: CERA-20C monthly
created by
Jan 12, 2017
-
Blog: New S2S origin: KMA is now available
created by
Jan 11, 2017
-
Blog: New Public Dataset: ERA5_test reanalysis
created by
Nov 04, 2016
-
Blog: New Public Dataset: CAMS GHG flux inversions
created by
Jul 20, 2016
-
Blog: New Public Dataset: S2S, ECCC, Reforecasts
created by
Jun 29, 2016
-
Blog: New Public Dataset: S2S, ECCC, Realtime
created by
Jun 22, 2016
-
Blog: New Public Dataset: CAMS NRT dataset
created by
Jun 22, 2016
-
Blog: New Public Dataset: CAMS Global Fire Assimilation System
created by
May 20, 2015
-
Blog: New Public Dataset: ERA-20C Monthly Means, ERA-20C Wave Monthly Means
created by
May 20, 2015
-
Blog: New Public Dataset: ERA-20C Daily, ERA-20C Wave, ERA-20C Observations
created by
May 13, 2015
-
Blog: New Public Dataset: S2S
created by
May 13, 2015
-
Blog: Limit target size
created by
Apr 29, 2015
-
Blog: Limit number of fields
created by
Apr 01, 2015