Context

The EDITO Data Catalogue complements the EDITO Data Storage to form the EDITO Data Lake, which represents the “data access” component of EDITO (find more details in this article).

As a reminder, the EDITO Data Catalogue can reference data inside EDITO storage or external data, whereas the EDITO Data Storage provides an elastic cloud object storage allowing users to store personal, group or public data.

As a user, you have two ways to interact with the EDITO Data Catalogue: via a Viewer (to browse and search) and via a Data API (to reference your own data if necessary).

📌 Note: only browsing/searching has a graphical interface (the Viewer). All write actions (creating catalogues, collections, items) go exclusively through the Data API.

Reminders

The EDITO Data Catalogue API is compliant with STAC and OGC API Features standards.

Especially, we use:

STAC Collections to classify data by scientific variables (wind speed, sea ice albedo, etc.). This is the objective classification of any data. Each collection represents a specific variable defined by a specific convention standard name definition. The collections are governed by the community, but moderated by the administrators.
STAC Items to represent homogeneous pieces of data (over the variable dimensions). Items are added and governed by the users. An item is necessarily inserted into a collection and refers to the scientific variable of the collection it belongs to, your item will automatically be attached to the collection matching its scientific variable when you publish it. Some item metadata are automatically generated to ease integration with other sub-system of EDITO or external systems.

⚠️ An item can be part of several catalogues but only one collection.

STAC Catalogues to classify data by alternative view or ordering (classification by variable families, such as “temperature”, “O2”, etc., personal catalogues, project catalogues). This is the subjective classification of any data. Catalogues are added and governed by the users. Some catalogue metadata are automatically generated to ease integration with other sub-system of EDITO or external systems.

Organization of the Data Catalogue through the Viewer

Default View - As a logged out user

Once you access the Integration Viewer, the interface looks like this:

(1): the list of available catalogs. You have the Copernicus Marine, EMODnet catalogues pinned at the top, along projects' catalogues, users' catalogues and finally a list of variable families from Copernicus Marine and EMODnet

💡 EDITO Pro Tip: by clicking on "EDITO Data Catalog" at the top you will also have access to several Data Collections.

(2): you can search for a catalogue using keywords
(3): your access to the user support
(4): to connect to the Viewer

⚠️ When logged out of your EDITO account, you will only have access to projects' catalogues (and collections and their items) made public by EDITO:

As a logged in user

Once you're logged into your EDITO account, you will have access to:

Public catalogues (Copernicus Marine, EMODnet and their content).
Catalogues associated with the projects you are part of (in the Projects Catalog section).

📌 Note: in these Project's Catalogues you will be able to see items that have been made visible to the project and to you. If you don't see anything:

There are no items
There are items, but they've been set to private by other project members

In the Users Catalog section you will see your own items, collections and catalogues if you have them.

Rights and permissions

As a user, your rights on the EDITO Data Catalogue depend on where you are:

In your own space

You can create items, collections and catalogues, you are the owner of your own space.

In a group space

⚠️ On EDITO, you can access shared workspaces. These are generally called “project spaces,” but they can also be simple group spaces that aren't linked to an official project or program.

Here, it depends on whether or not you are the owner of the group.

📌 Note: the owner of the catalogue is the first person who did an action on the group's catalogue or connected to the group the first time. Ownership can be transferred on request to User Support, though there is no self-service process for this yet.

If you are the owner of the group

You can create catalogues, collections and items.
You can give rights to members of the group. Permissions are managed separately for each of the three resource types: catalogues, collections, and items. For each of these, you can grant read, write, update, or delete rights independently, rather than as a single combined permission.
When you give rights, you give them to all members of the group.

If you are a member

By default you can read what's in the group's catalogue and create/publish items.
All members have the same rights as each other.

📌 Note: by default, all catalogues, collections and items are private. For catalogues and collections, making them public requires submitting a request to User Support. For items, users now have autonomy to make their own public directly. See "The visibility parameter" below for details.

How to add your own dataset in a catalogue

To reference your data in the EDITO Data Catalogue use the Data API.

Before you start, make sure you have the right permissions on the space you want to publish to:

In your own space, you're the owner, so you can create items, collections and catalogues directly.
In a group space, you need at least write permissions from the catalogue owner to create/publish items (see Rights and permissions above).

The visibility parameter

When creating a catalogue, collection or item, the visibility parameter is required. It's an array and accepts the following values:

"visibility": ["{groupname}", "{username}_private"]

{groupname}: makes the object visible to all members of that group/project.

{username}_private: keeps the object private to you, visible only in your own space.

📌 Note: there's also a special value, "default", which makes the object public. It can only be set for objects belonging to the default group (not other project/group spaces).

Setting it yourself directly will return a 403 error: for catalogues and collections, making an object public requires submitting a request to User Support, with evidence of the project's progress and a justification. For items, you have autonomy to make them public directly through the API.

For example, to create a collection in your own personal space (private to you only):

curl -X POST 'https://api.dive.edito.eu/data/collections' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --data '{
    "id": "ocean_temperature_products",
    "type": "Collection",
    "title": "My Ocean Temperature Products",
    "description": "Sea surface temperature datasets from my project.",
    "visibility": ["my-username_private"]
  }'

📌 Note: replace my-username with your own EDITO username. If you wanted this collection visible to a group instead, you would add its name to the array, e.g. "visibility": ["my-group", "my-username_private"].

📌 Note 2: for catalogues and collections, visibility sits at the top level of the object. For items, it goes inside the properties object instead.

Linking an external catalogue

The current method is to POST a catalogue under the /catalogs endpoint with the stac_url parameter set to the external catalogue's URL. It will appear as a child under its parent catalogue. Note that only one external child catalogue is allowed this way.

Using the Data API

The base URL to interact with the catalogue is https://api.dive.edito.eu/data. You can:

List and inspect collections (/collections, /collections/{collectionId})
List, retrieve, and create items within a collection (/collections/{collectionId}/items), using a POST request with a STAC-compliant item and a bearer token
Create, update, and delete catalogues (/catalogs). Items are attached to a catalogue via links (rel: item) in the request body. Catalogues and collections, on the other hand, are attached by POSTing the full object directly to /catalogs/{parent}, they cannot be linked manually via links.
Search across everything using /search, by bounding box, owner, or catalogue name

Your dataset itself must be hosted somewhere accessible (for example in your EDITO personal or group storage, made publicly shared), since the API only stores the metadata pointing to it, not the data itself.

This requires an access token and some familiarity with STAC's item/catalogue structure. For the full list of endpoints and request examples, see this article.

General example

This example walks through creating your own catalogue, adding a collection to it, and publishing an item into that collection, all in your personal space (private to you).

Create your personal catalogue (if you don't already have one)

curl -X POST 'https://api.dive.edito.eu/data/catalogs/users' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --data '{
    "id": "my-username",
    "type": "Catalog",
    "title": "My catalogue",
    "description": "My personal catalogue"
  }'

Create a collection and attach it to your catalogue

curl -X POST 'https://api.dive.edito.eu/data/catalogs/my-username' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --data '{
    "id": "ocean_temperature_products",
    "type": "Collection",
    "title": "My Ocean Temperature Products",
    "description": "Sea surface temperature datasets from my project.",
    "visibility": ["my-username_private"]
  }'

Publish an item into that collection

curl -X POST 'https://api.dive.edito.eu/data/collections/ocean_temperature_products/items' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --data '{
    "id": "my-item",
    "type": "Feature",
    "properties": {
      "datetime": "2023-01-12T09:01:00Z"
    },
    "geometry": { "type": "Polygon", "coordinates": [[[0,0],[0,0],[0,0]]] },
    "assets": {
      "data": { "href": "<URL_TO_YOUR_DATA>", "title": "data", "roles": ["data"] }
    },
    "visibility": ["my-username_private"]
  }'

Your item is now published, visible only to you, and automatically classified under the scientific variable of the collection it belongs to.

💡 EDITO Pro Tip: for the complete list of endpoints, request parameters and response formats, you can browse the interactive API documentation. You can test requests directly from your browser, without writing any code.

What's next?

If you have any questions, problems, or suggestions, please feel free to contact us via chat using the widget available at the bottom right of the page.

Use the EDITO Data Catalogue