Context

As part of the transition to WEkEO 2.0, the Harmonized Data Access (HDA) also has undergone a significant evolution. The most significant changes to the API are:

Synchronous jobs for search and download
Faster search results with pagination
Simplified syntax of the search request

Let's dive deeper into the improvements and changes to consider of HDA V2! 💪

Improvements of HDA V2

One of the main enhancements of the HDA V2 is the simplified query syntax.

Here is a comparison between old and new HDA query:

Old HDA request syntax (click me)

{
"datasetld": "EO:EUM:DAT:METOP:GLB-SST-NC",
"dateRangeSelectValues": [
  {
    "name":"position",
     "start":"2016-07-11T05:58:00.000Z",
     "end":"2016-07-12T00:00.000Z",
  }
],
"stringChoiceValues":[
  {
    "name":"sat",
    "value":"Metop-B"
  },
  {
    "name":"type",
    "value":"OSSTGLBN"
  }
]
}

New HDA request syntax (click me)

{
"dataset_id": "EO:EUM:DAT:METOP:GLB-SST-NC",
"dtstart": "2016-07-11T00:00:00.000Z",
"dtend": "2016-07-12T00:00:00.000Z",
"sat": "Metop-B",
"type": "OSSTGLBN"
}

We clearly see the differences: the new HDA query is a lot more compact and easy to build and read.

Then, the new HDA API is made more user-friendly and simplifies the process of searching and downloading through the use of the hda Python library.

Also the CliMetLab plugin from WEkEO simplifies the process of downloading data and working with various data formats for users, while also providing a more user-friendly way to display data.

Changes to apply with HDA V2

There are a few changes to take into consideration with the HDA V2:

You must convert your queries from old to new syntax as the example given in previous section. The old syntax is not working anymore
You must delete the URL in your existing .hdarc file if it still contains it. Otherwise, you will encounter an error with the HDA V2.
When using the HDA REST API, you need to run the following commands to obtain or refresh a token (a token has to be refreshed every hour):
- Command curl to request a token:
```
curl -X POST -H 'Content-Type: application/json' -d '{"username":"USERNAME","password":"PASSWORD"}' https://gateway.prod.wekeo2.eu/hda-broker/gettoken
```
- where USERNAME and PASSWORD must be replaced with your WEkEO credentials.
  
  This is how you can retrieve your access token:
```
{"access_token":"29020185-xxxx-xxxx-xxxx-78626d0xxxx", [...]}
```
- Command cURL to refresh a token:
```
curl -d "refresh_token=REFRESH_TOKEN" https://gateway.prod.wekeo2.eu/hda-broker/refreshtoken
```
- where the REFRESH_TOKEN is provided by the first call of gettoken like this:
```
{"access_token":"xxxxxx","refresh_token":"xxxxx", [...]}
```

Complete example to create and refresh a token (click me)

Request a token (replace USERNAME and PASSWORD with your WEkEO credentials):

curl -X POST -H 'Content-Type: application/json' -d '{"username":"USERNAME","password":"PASSWORD"}' https://gateway.prod.wekeo2.eu/hda-broker/gettoken

Returns:

{"access_token":"52ae8f0d-1bbf-3f3b-a9b1-f610faba521a",
"refresh_token":"ecd1886e-b7ed-3e1c-9aa9-76bc2df9e494",
"scope":....,
"expires_in":3600}

Refresh the token:

curl -d "refresh_token=ecd1886e-b7ed-3e1c-9aa9-76bc2df9e494" https://gateway.prod.wekeo2.eu/hda-broker/refreshtoken

Returns:

{"access_token":"662d58a3-200d-3dca-a51c-05cfad23f350",
"refresh_token":"e2077f52-3fe9-3660-8cee-f2a9acb6c64b",
"scope":....,
"expires_in":3600}

This command gives you a new token valid for 1 hour.

💡 WEkEO Pro Tip: you can visit the HDA Broker containing detailed information on the HDA features, with short descriptions and test functionality.

What's next?

Additional resources can be found in our Help Center. Should you require further assistance or wish to provide feedback, feel free to contact us through a chat session available in the bottom right corner of the page.

HDA API errors

How to use the HDA API in Python?

How to use the Harmonized Data Access REST API with cURL?

How to use the hdar package for accessing the WEkEO HDA API in R?

What is the Harmonized Data Access (HDA) API?

Improvements brought by HDA V2

Context

Improvements of HDA V2

Changes to apply with HDA V2

What's next?