Purpose

This tool allows querying and downloading of (mainly) meteorological data provided by the European Center Medium Weather Forecast (ECMWF). Such information is public available and procedurally accessible through a dedicated Web-API (http://apps.ecmwf.int/datasets/) that interacts with their databases. At the moment, this tool uses the "ERA5" dataset, which contains global reanalysis data from January 1979 to present computed each hour and with a granularity of about 30km.

Although the information is freely accessible, an account must be first created as login credentials are required by this tool to perform queries. If you don't have an account yet, please apply at https://cds.climate.copernicus.eu/user/register and get one. You then have to do two additional steps before using this tool: 1) obtain your Web-API key and username (UID), and 2) accept the service terms and conditions.

To retrieve the Web-API key and the username, once registered, you need to go to your profile page where you will find them at the bottom marked as KEY and UID respectively

Please keep in mind that you have to enter the UID in the username field of the SARscape ECMWF ERA5 Download panel and the Web-API key in the key field!

Before being able to access the ECMWF datasets, you have to agree to the corresponding terms and conditions that can be found under the "Licence" link at https://software.ecmwf.int/wiki/display/WEBAPI/Available+ECMWF+Public+Datasets. To use this tool accepting the general license is sufficent.

Technical Note

This tool performs a search for ECMWF ERA5 data according to the query built through the input parameters: the tool is responsible for searching, downloading and processing the information for its usage within SARscape.

When started from the SARscape graphical user interface (under Import Data→ECMWF ERA5 Download), the query is executed and, depending on several factors such as its complexity and ECMWF ERA5 service traffic, can take a significant amount of time to complete.

ECMWF policies about data downloading are subject to vary over time and some specific restrictions apply, for example regarding the maximum temporal span or the number of fields that can populate one single query. Please refer to the ECMWF ERA5 documentation for further details. In case of failed download, users should reduce the temporal span to be downloaded.

A query is built through the many input parameters that users can customize to their needs. These input parameters are then automatically translated into the proper ECMWF ERA5 Web-API series of instructions that leads to the generation and acquisition of the required information. This information is also automatically converted into files that are natively supported by SARscape, including the automatic generation of series to see their evolution through animations. As a rule of thumb, a separate file is created for each observed day/hour.

The customization of the many input parameters cover a series of different cases that should simplify the acquisition of ECMWF data related to the user's needs. Users should first identify which kind of meteorological information to query by selecting one of the fields specified under the "Parameter" field. Those parameters cover information such as temperature, cloud cover, soil water, etc. For more detail about the very description of each parameter, please refer to the official documentation provided by ECMWF.

Once defined the kind of meteorological information, users have to specify a temporal interval and a geographical area. The first is done by entering the starting and ending date under the "From" and "To" fields. In addition, users have to specify at which hour(s) of the days within the temporal interval data should be downloaded. The ECMWF Era5 dataset provides results at hourly intervals. One or multiple hours can be selected, this can be done by selecting the corresponding hours in the measurement hours field separated by a comma (,) (an example is given as a default value in the panel). The hours should be written in military time (24h) and only on the hour times are supported, adding minutes might produce incorrect results.

The geographical area is specified through its starting/ending latitude and longitude coordinates, expressed in degrees.

A simple query is then completed by specifying the desired output projection (under the DEM/Cartographic tab) and output file root name (under the Output Files tab).

More advanced queries can be performed by letting the tool extracting the temporal interval and/or geographical area directly from input files. Users can specify an input shape file under the Optional Files tab. In that case, the query will automatically use a lat/lon bounding box surrounding the input shape file instead of the explicit coordinates specified under the Parameters tab. If no image is included as reference and no measurement hour in selected, the query will request from the server the measurement taken at 12:00 for every day in the interval.

Users can also put one or more files in the file list under the Input Files tab. In that case, the tool will automatically analyze such files and extract the temporal interval from the oldest and newest file, as well as constructing a lat/lon bounding box large enough to encompass the area covered by all the files. When this approach is used to specify the temporal interval and geographical area, the time of the measurement taken will be the same one as the acquisition time of the image. In this case the requested file will contain the data for all the days between the oldest and most recent input image but only the ones that match the input images will be extracted in a SARscape compatible format.

Please note that a maximum of 4 requests can be simultaneously performed by a user, trying to start a fifth will result in an error when the data will become available on the server (potentially after quite some time).

Input Files

Optional Input Files

Input file(s) name of the image to be used as geographic reference and measurement time for the search query. These files are mandatory if no shapefile or coordinate box is given as a reference. These files can be geocoded files, slant range or ground range files. However, the data type of the whole list has to be the same.

Optional Files

Input reference shape

Shape file of a geographic region. All acquisitions inside or intersecting this polygon are returned. Shape file must be in GEO-GLOBAL cartographic system.

DEM/Cartographic System

Output Projection

The following parameters are compulsory to define the Cartographic System:

State

Definition of the country or general projection systems.

Hemisphere

Definition of the hemisphere. This is chosen according to the selected State and Projection.

Projection

Definition of the projection system of the selected State. In case that a general projection system is selected in State, the Projection is automatically set.

Zone

Definition of the zone. This is chosen according to the selected State and Projection.

Ellipsoid

Definition of the ellipsoid. This is chosen according to the selected State and Projection.

Datum Shift

Definition of the datum shift parameters. These are chosen according to the selected State and Projection.

Reference Height

In case that the Digital Elevation Model is not used, a constant ellipsoidal height must be provided. Default Reference Height is 0.

Parameters - Principal Parameters

Parameter

Definition of the product type. The following parameters can be selected:

Volumetric soil water layer 1, Volumetric soil water layer 2, Volumetric soil water layer 3, Volumetric soil water layer 4, Surface pressure, Total column water vapor, Total cloud cover, Soil temperature level 1, Soil temperature level 2, Soil temperature level 3, Soil temperature level 4, 2 meter temperature, 2 meter dew point temperature, Snow density, Snow depth, Skin reservoir content, Skin temperature, Log of surface roughness for heat).

The default value is “2 metre temperature”.

From

Sensing period start date (day-MONTH-year), dd-MMM-yyyy, (01-JAN-1970).

Sensing period stop date (day-MONTH-year), dd-MMM-yyyy, (01-JAN-1970).

Measurement hours: Delivery time of ECMWF ERA5 dataset results separated by comma (,) and written in military time (E.G. 00:00, 01:00, ...). They don’t have to be subsequent hours.

Geographic Region

Box coordinates. All acquisitions inside or intersecting this box are returned. These fields have to be left empty if a shapefile is used as spatial reference. Co-ordinate decimal values must be entered using the dot (e.g. 29.30) and not the comma (e.g. 29,30) character.

Initial longitude

The Westernmost cartographic co-ordinate (in decimal degrees).

Final longitude

The Easternmost cartographic co-ordinate (in decimal degrees).

Initial latitude

The Northernmost cartographic co-ordinate (in decimal degrees).

Final latitude

The Southernmost cartographic co-ordinate (in decimal degrees).

X Grid Size

The grid size of the output data in Easting (X) must be defined only if the Reference file is not used; the default unit of measure is meters.

Y Grid Size

The grid size of the output data in Northing (Y) must be defined only if the Reference file is not used; the default unit of measure is meters.

Username (UID) of ECMWF ERA5 Web-API login credentials. This field is mandatory.

Web-API key of ECMWF ERA5 Web-API login credentials. This field is mandatory.

Proxy - URL

If a proxy server is being used for accessing the external network, write here the server address.This field is optional.

Proxy - USERNAME

If the proxy server requires a username put it here.This field is optional.

Proxy - PASSWORD

If the proxy server requires a password, put it here.This field is optional.

Parameters - Global

It brings to the general section of the Preferences specific parameters. Any modified value will be used and stored for further processing sessions.

ECMWF ACCOUNT

It brings to the User account section of the Preferences common parameters. Any modified value will be used and stored for further processing sessions.

Username (UID) of ECMWF ERA5 Web-API login credentials. This field is mandatory.

Web-API key of ECMWF ERA5 Web-API login credentials. This field is mandatory.

Proxy - URL

If a proxy server is being used for accessing the external network, write here the server address.This field is optional.

Proxy - USERNAME

If the proxy server requires a username put it here.This field is optional.

Proxy - PASSWORD

If the proxy server requires a password, put it here.This field is optional.

ECMWF SERVICE

Base URL

It allows setting the ECMWF Web-API entry point (https://cds.climate.copernicus.eu).

Service URL

String to be appended to base URL to perform search queries (/api/v2/resources/).

Task URL

String to be appended to base URL to check the request status (/api/v2/tasks/).

Connection timeout

Connections have to success before this time out, in seconds, is triggered.

Download timeout

A threshold value, in seconds, after which "Download Speed" bytes must be downloaded, otherwise the connection is considered lost and an error is triggered.

Max number of iterations

The maximum number of times a status check will be performed before the file will be deemed unobtainable.

Download Directory

A specific folder is set, where the required ECMWF ERA5 files are stored.

Parameters - Other Parameters

Parameter

Definition of the product type. The following parameters can be selected:

The default value is “2 metre temperature”.

From

Sensing period start date (day-MONTH-year), dd-MMM-yyyy, (01-JAN-1970).

Sensing period stop date (day-MONTH-year), dd-MMM-yyyy, (01-JAN-1970).

Measurement hours: Delivery time of ECMWF ERA5 dataset results separated by comma (,) and written in military time (E.G. 00:00, 01:00, ...). They don’t have to be subsequent hours.

Geographic Region

Initial longitude

The Westernmost cartographic co-ordinate (in decimal degrees).

Final longitude

The Easternmost cartographic co-ordinate (in decimal degrees).

Initial latitude

The Northernmost cartographic co-ordinate (in decimal degrees).

Final latitude

The Southernmost cartographic co-ordinate (in decimal degrees).

X Grid Size

The grid size of the output data in Easting (X) must be defined only if the Reference file is not used; the default unit of measure is meters.

Y Grid Size

The grid size of the output data in Northing (Y) must be defined only if the Reference file is not used; the default unit of measure is meters.

Output Files

Output Root Name

Name of the output root. This file is mandatory.

General Functions

Exec

The processing step is executed.

Store Batch

The processing step is stored in the batch list. The Batch Browser button allows to load the batch processing list.

The window will be closed.

Help

Specific help document section.

Specific Function(s)

None.

References

None.

Import Data - ERA 5 Download

Import Data - ERA 5 Download

Purpose