Welcome to EDEN’s documentation

Introduction

EDEN is the primary gateway for accessing an extensive array of environmental data sourced from EUMETSAT’s Data Lake and ECMWF’s Digital Twin Engine.

This guide aims to provide comprehensive instructions on engaging the service through two distinct access points:

Section 1 illustrates the Finder, the web-based interface granting a user-friendly access.
Section 2 explains how to leverage the Service through APIs, for users seeking a more programmatic approach.

User quotas

To ensure optimal resource management and user experience, the following quotas have been allocated to the default user type:

Search Quota: Users can perform up to 100 searches per hour.
Simultaneous Quota: Users can have up to 10 orders in running status at any given time.
Download Quota: Users can download up to 10 orders per hour.
Stream Quota: Users can have up to 2 simultaneous parallel downloads in progress at once.

Section 1: The Finder

The Finder is EDEN’s user-friendly interface to effortlessly access DESP’s Data Catalogue. Following below, you will learn how to navigate it with confidence and efficiency.

For the best user experience, we advise keeping your browser of choice up to date. This ensures compatibility with the latest features and optimisations implemented on the app.

Getting started

Before diving into the key functions of the app, let’s get acquainted with the user interface through some preliminary information.

Glossary

The key concepts of EDEN are:

Collections: Each collection represents a set of EO data within the catalogue, defined by its unique use cases, metadata attributes, or user community it serves.
Products: Data granules within the collection are labelled as products. Products contain the actual EO data you can access for your projects and research.

Interface walkthrough

Upon landing on the Finder, you will find the list of available collections in the collapsible sidebar on the left. There, you can also see how many have been uploaded in relation to the total.

After scrolling down, you can quickly return to the top of the list by clicking ↑.

The service offers a two-step search approach to support your journey for data discovery, access, and visualisation: the first step involves discovering collections, while the second focuses on searching for data within a specific collection.

Adjusting the map’s visualisation

Familiarise yourself with the following basic gestures to smoothly navigate the map on whichever device you choose.

Action	On PCs	On touch devices
Zoom in/out	Scroll with your mouse wheel	Pinch the screen
Pan	Hold the left button of your mouse and swipe it in any direction	Swipe in any direction
Tilt ¹	Hold the mouse wheel and drag in any direction	Double swipe in any direction

¹ Please note that this action is available for 3D and Columbus projections only.

Data access & retrieval

This section provides guidance on how to apply first- and second-step filters and the options to interact with the products.

Attention

Please note that authentication is required: click the “Sign in” button on the upper-right corner of the app to login or create a new account.

Browsing for data

To perform a search in the collections catalogue, you have two options:

Perform a targeted search: Enter the name, part of the name, or dataset ID of a collection into the Free text field.
Search for any collection matching specific criteria: Scroll the mouse wheel over the Free text field, or click + to display all available filtering parameters.

The collections list will automatically update in response to your input.

Once you have found a collection of interest, you can narrow the search for relevant data, by applying:

Collection-specific filters: Click icon ③ to open the dedicated modal. Please note that filters marked with a red asterisk are mandatory. If they are not applied before clicking ‘Browse’, the modal will automatically open, prompting you to complete the required fields.
Spatial filters: Click icon ④ to draw your area of interest on the map. Please note that only one drawing is allowed at a time; drawing a new area will consequently reset your current search.

Options to browse collections and filter products

Tip

If you wish to learn more about collections, click ⓘ on their cards to open a modal with comprehensive insights.

Finally, click “Browse” to perform the search.

Accessing the products

When a search is performed, relevant products will be concurrently displayed in the sidebar and on the map through their respective geometries, if available.

The sidebar shows the count of returned products in relation to the total (at the top) and features navigation buttons (at the bottom) to move through the pages of results one at a time, with each page displaying up to 10 products. After scrolling down, you can quickly return to the top of the list by clicking ↑.

Tip

Click the “Filters” button between navigation buttons to modify your search parameters.

Product cards typically display information such as their date and thumbnail, if available. In addition, various features are enabled based on the services available for the collection. More specifically:

① - Zoom to the product’s location on the globe, or resets the camera view if the product is global.
② - Toggle the visualisation of the Web Map Service (WMS).
③ - Add the product to cart, or remove it when it has been previously added.
④ - Show more product information.

Overview of features associated to products

Using the cart

Step 1: Add the products of interest to the cart by clicking the corresponding icon on their card.
Step 2: Open the Cart modal by clicking the corresponding icon on the upper-right corner of the page.
Step 3: Click “Submit order”: while waiting for the process, you can close the modal but not the Finder webpage.
Step 4: Once the product is ready for retrieval, click “Download” to save it on your device.

Attention

Please note that authentication is required: click the “Sign in” button on the upper-right corner of the app to login or create a new account.

Customisation

This section illustrates the various options to tailor the Finder’s interface to your preferences.

Map base layer

Click icon ③ to to switch between the base layers: Aerial (geographic map) and Roads (political map). In particular, the language of the Roads layer is automatically adjusted to match your device’s settings.

Map projection

Click icon ④ to switch among map projections: 2D, 3D and Columbus. All of them allow you to:

Navigate on the map,
Visualise the products footprints and WMS layers,
Draw geometries,

Theme settings

The Finder provides the following themes:

The Light Mode uses light colours for background and text, which is ideal if you prefer a bright interface.
Opt for the Dark Mode if you prefer a darker background and lighter text, which can reduce eye strain in low-light environments.
The System Mode synchronises the app’s theme with the system settings of your device.

You can switch between them by clicking icon ⑥, which appears as the visual indicator of the current theme. Each click will immediately switch the app to the next available theme.

The app will cycle through the themes in this sequence: Light Mode, Dark Mode, and System Mode. Continue clicking until you reach your desired theme. The app will maintain your settings until you delete the browser cache.

Additional perks

The Finder provides the following features to enhance your user experience:

① - Reset the camera position on the map.
② - Toggle the countries’ borders on the map.
⑤ - If a WMS is enabled on the map, toggle the visualisation of its colour table.

Section 2: Consuming APIs

This section provides information on engaging the Service via APIs.

Harmonised Data Access (HDA)

The HDA is the core API enabling access to every collection distributed across several data sources, regardless their heterogeneous data types.

You can delve into the APIs features and interactively test them by visiting our Swagger page.

Attention

Please note that an authentication token is an essential prerequisite for leveraging the APIs.

Data discovery

Request	Description	Required parameters
GET `/api/v1/datasets`	Retrieve the Catalogue of all enabled collections	N/A ²
GET `/api/v1/catalog/queryable`	Retrieve the list of applicable metadata to filter the catalogue	N/A
GET /api/v1/dataaccess/queryable/{dataset_id`}	Retrieve the list of applicable parameters to filter a collection	`dataset_id` (e.g. `EO:EUM:DAT:0000`)
GET `/api/v1/datasets/{dataset_id}`	Retrieve the products list of a specific collection	`dataset_id` (e.g. `EO:EUM:DAT:0000`)

² The query enables the following optional parameters: q (free text search), startIndex (index of the first dataset returned), ItemsPerPage (number of datasets returned per page)

Below are some examples of common queries:

{
    "dataset_id": "EO:MEEO:DAT:REANALYSIS_ERA5_LAND:COG",
    "subDatasetId": "2m_temperature",
    "startDate": "2024-05-01T00:00:00.000Z",
    "endDate": "2024-05-02T00:00:00.000Z",
    "itemsPerPage": 10
}

{
   "dataset_id": "EO:MEEO:DAT:REANALYSIS_ERA5_LAND:COG",
   "bbox": [
      -3.9937457793584943,
      47.78420129354401,
      32.49546625807707,
      23.337970635735623
   ],
   "subDatasetId": "2m_temperature",
   "startDate": "2024-05-01T00:00:00.000Z",
   "endDate": "2024-05-02T00:00:00.000Z",
   "itemsPerPage": 10
}

Data access & retrieval

To obtain data of a specific product, execute the following API call:

Request	Description	Required parameters
POST `/api/v1/dataaccess/search`	Forward the search request to the data source	Json with bboxes (defined as UL-lon, UL-lat, LR-lon, LR-lon), dates in YYYYMMDDTHH:MM:SS.MMMZ format, string variables (string), integer variables (int), float variables (float), an array of string \| int \| float

How to download products

Below is the step-by-step procedure to procure your data of interest:

Step	Command line	Description	Required parameters
1	POST `/api/v1/dataaccess/download`	Forward the download request to the data source	`dataset_id`, `product_id` and `location` returned by search
2	HEAD `/api/v1/dataaccess/download/{download_id}`	Check if the requested product is ready to be downloaded	`dataset_id` (e.g. `EO:EUM:DAT:0000`)
3	GET `/api/v1/dataaccess/download/{download_id}`	Download the requested product	`dataset_id` (e.g. `EO:EUM:DAT:0000`)

Moreover, you can oversee the pending downloads via the following APIs:

Command line	Description	Required parameters
GET `/api/v1/dataaccess/downloads`	Return the list of all downloads you required	N/A ³
DELETE `/api/v1/dataaccess/download/{download_id}`	Remove a download from the list	`download_id`

³ The query enables the following optional parameters: download_id, startIndex (index of the first dataset returned), ItemsPerPage (number of adapters returned per page).

Terms & Conditions management

Some collections may require you to accept the Terms & Conditions of Service of their Data Provider. To do so, make the following API call:

Command line	Description	Required parameters
PUT `/api/v1/termsaccepted/{term_id}`	Accept specific T&C	`term_id`

Moreover, you can review the Terms & Conditions you have accepted through the following APIs calls:

Command line	Description	Required parameters
GET `/api/v1/termsaccepted`	Retrieve the list of T&C accepted	N/A ⁴
GET `/api/v1/termsaccepted/{term_id}`	Retrieve a specific T&C accepted	`{term_id}`
DELETE `/api/v1/termsaccepted/{term_id}`	Revoke acceptance of specific T&C	`{term_id}`

⁴ The query enables the following optional parameters: startIndex (index of the first accepted T&C returned), ItemsPerPage (number of accepted T&C returned per page)

OpenSearch

OpenSearch is an highly scalable and extensible open-source software suite for search, analytics, observability, and other data-intensive applications. If you wish to learn more about this Standard, please refer to the OpenSearch official website

All queries may be executed as simple HTTPS-Get calls by typing the query in the web browser address line; results are produced in JSON format. The query must be specified as a formal query, which is invoked as a sub-phrase sequence,

The EDEN OpenSearch catalague is accessible freely and anonymously (no authorization is required). Following below are some examples to retrieve your data of interest:

API endpoint	Description	Example
`/datasets`	Retrieve all datasets	https://opensearch.eden.destine.eu/opensearch/datasets>
`/search`	Retrieve the products of a dataset	https://opensearch.eden.destine.eu/opensearch/search>
`/description/{datasetId}`	Retrieve the filtering parameters of a dataset	https://opensearch.eden.destine.eu/opensearch/description/{EO:MEEO:DAT:REANALYSIS_ERA5_SINGLE_LEVELS_MONTHLY_MEANS:COG}>

To narrow the search for relevant data, the following parameters can be added to the query:

startDate, endDate: the date limits of the observation (e.g.2024-02-26T00:00:00Z).
geometry: region of interest (e.g. {“type”:”Point”, coordinates: -179.875, 90.0}). If the values in a clockwise direction, the results will be provided outside the geometry. Conversely, when expressed counter-clockwisely, they will be provided within the geometry.

The parameters can be invoked individually or jointly, separated by &. The result is a conjunction of all sub-phrases, such as https://opensearch.eden.destine.eu/opensearch/search/EO:MEEO:DAT:REANALYSIS_ERA5_SINGLE_LEVELS_MONTHLY_MEANS:COG?maxRecords=10&startIndex=0

STAC

STAC (SpatioTemporal Asset Catalog) is a specification that standardizes the way geospatial assets are described and accessed, facilitating interoperability and discovery across different platforms and tools.

The EDEN STAC catalague is accessible freely and anonymously (no authorization is required).Following below are some examples to retrieve your data of interest:

API endpoint	Description	Example
`/`	Describe the capabilities of the Catalogue	https://stac.eden.destine.eu/stac/>
`/service-desc`	Describe in OPENAPI format all APIs exposed by STAC	https://stac.eden.destine.eu/stac/service-desc>
`/conformance`	Explain which standards the STAC conforms to	https://stac.eden.destine.eu/stac/conformance>
`/collections`	Access information about all collections	https://stac.eden.destine.eu/stac/collections>
`/collection/<datasetId>`	Access information about a specified collection	https://stac.eden.destine.eu/stac/collections/EO:ECMWF:DAT:REANALYSIS_ERA5_LAND_MONTHLY_MEANS>
`/collection/<datasetId>/items`	Search for the products of one collection	https://stac.eden.destine.eu/stac/collections/EO:ECMWF:DAT:REANALYSIS_ERA5_LAND_MONTHLY_MEANS/items>

If you wish to delve further into the STAC ecosystem, please consult STAC’s official library of tutorials.

OGC Standards

OGC’s free and open geospatial Standards define interoperable approaches to Data Encoding, Data Access, Data Processing, Data Visualization, and Metadata and Catalogue Services. For more information on how to get started on using them, please refer to the Standards official documentation

The Web Map Service (WMS) standard allows to request and retrieve map images over the internet. To access this functionality, please refer to EDEN WMS API Documentation. Whenever the service is available for a collection, the OpenSearch catalogue exposes the products’ WMS links.
The Web Coverage Service (WCS) standard enables access to geospatial coverage data, enabling users to retrieve raw data rather than rendered images. Please Note: The WCS is under development and not available at this time. However, we are actively working on implementing this functionality in the near future, stay tuned for updates!