Harmonised Data Access API

The Harmonised Data Access API is a REST interface allowing users to subset and download WEkEO datasets. The following sections describe the API from the dynamic and static points of view.

Note that the endpoints in this document are available at the following broker address:

https://apis.wekeo.eu/databroker/0.1.0
example: https://apis.wekeo.eu/databroker/0.1.0/querymetadata/{datasetId})

Quick Reference

WEkEO HDA API supports the dataset search and data download operations via RESTful interface. Access token is required to work with the API which can be generated from the following endpoint using API Key. Note that this endpoint is a HTTP POST operation and expects Authorization field in header and 'grant type' in the body.

https://apis.wekeo.eu/token

Data Broker API

The API endpoints in the table below must be prefixed by the broker address specified above.

example: https://apis.wekeo.eu/databroker/0.1.0/querymetadata/EO%3AEUM%3ADAT%3ASENTINEL-3%3AOL_2_WRR___

HTTP Operation	API endpoint (prefixed by broker_address)	Description
GET	/querymetadata/{datasetid}	This returns the parameters/metadata that are available for querying the dataset specified by {datasetid}. The response also includes the infromation if the user has accepted the Terms & Conditions of the dataset {datasetid}. Example: https://apis.wekeo.eu/databroker/0.1.0/querymetadata/EO%3AESA%3ADAT%3AS…
POST	/datarequest	Using the API, one can submit a query (as JSON payload) constructed based on the queryable parameters returned by GET operation above. If the query is successfully submitted, then the response is a JSON with jobIB field
GET	/datarequest/status/{jobId}	The current status of the submitted job (started, running, completed, failed) can be obtained by using the API endpoint. If the job is successfully completed, the result is an array of strings of the form /datarequest/result/{jobId}. This string when appended to the broker address forms the URL to download the data
GET	/datarequest/jobs/{jobId}/result	API endpoint provides pagination limiting the number of items per request. Parameters for page number and the number of results per page can be used to fetch only the necessary results. The page number are numbered from 0 (i.e. first page is numbered 0)
GET	/datarequest/result/{jobId}?externalUri={externalUri}	This endpoint can be used to download a specific data from the result set
GET	/datarequest/jobs	This returns JSON object containing all the jobs submitted by the user along with the job status and result array for each of the job

Terms and Conditions API

The API endpoints in the table below must be prefixed by the following T&C's endpoint

https://apis.wekeo.eu/dcsi-tac/0.1.0
example: https://apis.wekeo.eu/dcsi-tac/0.1.0/termsaccepted/Copernicus_General_License

HTTP Operation	API endpoint (prefixed by broker_address)	Description
GET	/termsaccepted	This endpoint returns all the IDs of the different terms and conditions. Example: [Copernicus_General_License]
GET	/termsaccepted/{termId}	This endpoint returns boolean flag indicating if the user has accepted or not the Terms and Conditions of the {termId}. Example response: {"termId":"Copernicus_General_License","accepted":true}
PUT	/termsaccepted/{termId}	The request sets the acceptance of the Terms and Conditions of the {termId} to True, meaning user has accepted the conditions

Dynamic description

This section describes the Harmonised Data Access API from a dynamic perspective, showing each user request in context. For the detailed description of all API messages and responses, refer to the "Static description" section below.

Let's assume a user wants to access data in a given dataset. The user starts by sending a message to the Harmonised Data Access Broker at /querymetadata to obtain the list of parameters she can use to subset the data (see figure below). The response to this message includes an indication on whether the user has accepted the terms and conditions for this particular dataset. If not, the user can access the User Profile Service to update her profile.

The user then sends a request to /datarequest providing the desired subsetting parameters (e.g. bounding box) and immediately gets a subsetting job ID in return (see figure below).

With the job ID, the user can poll the Broker at /datarequest/status/{jobId} to determine when the job has finished and the data is available for download (see figure below). The Broker replies with either complete = false or complete = true.

If the job has completed, then the results can be obtained by invoking /datarequest/jobs/{jobId}/result endpoint. The response contains list of external URIs to data.

Then the user downloads the data via the /datarequest/result/{jobId}?externalUri={externalUri} endpoint.

The list of all the jobs submitted by the user can be obtained from the /datarequest/jobs endpoint.

Static description

GET /querymetadata/{datasetId}

Parameters:

datasetId (in the URL), required, string: ID of the dataset

Responses:

Code 200 (OK): a JSON object containing:
- datasetId, required, string
- userTerms, object:
  - termsId, string: unique label for the terms and conditions for the licence that must be accepted to use this dataset
  - accepted, boolean: whether the user has accepted or not the terms and conditions for the dataset
- parameters, object:
  - stringInputs, Array<StringInput>, where StringInput is an object containing all Parameter attributes described below, and in addition:
    - details, required, object:
      - maxLength, required, integer: maximum length of the input value
      - pattern, string: regex used to validate the input value
  - stringChoices, Array<StringChoice>, where StringChoice is an object containing all Parameter attributes described below, and in addition:
    - details, required, object:
      - valuesLabels, required, object mapping internal values to human-readable labels
  - multiStringSelects, Array<MultiStringSelect>, where MultiStringSelect is an object containing all Parameter attributes described below, and in addition:
    - details, required, object:
      - groupedValueLabels, required, Array<object>: each object contains:
        name, required, string: a human-readable name for the group
        
        label, string: a human-readable label to complement the name
        
        values_labels, object mapping internal values to human-readable labels
      - defaultValues, Array<string>
  - dateRangeSelects, Array<DateRangeSelect>, where DateRangeSelect is an object containing all Parameter attributes described below, and in addition:
    - details, required, object:
      - start, required, string in date-time format
      - end, required, string in date-time format
      - defaultStart, string in date-time format
      - defaultEnd, string in date-time format
  - boundingBoxes, Array<BoundingBox>, where BoundingBox is an object containing all Parameter attributes described below, and in addition:
    - details, required, object:
      - extent, required, Array<float> (4 elements)
      - crs, string enum (EPSG:4326)
- constraints, Array<Constraint>: list of inter-parameter constraints. Constraint is an object containing:
  - name, required, string
  - comment, string
  - constraintType, string
- rendering, Array<RenderingControl>: list of rendering options for the parameters and constraints, for UI use. Not required to construct a queryRequest. RenderingControl is an object containing:
  - name, required, string
  - comment, string
  - renderType, required, string

Parameter objects include:

name, required, string: internal name of the parameter
label, string: human-readable label to refer to this parameter
comment, string: human-readable descriptive text to complement information on this parameter
isRequired, require, boolean: whether the parameter is required in order to request data from this dataset

POST /datarequest

Parameters:

queryRequest (message body), required, JSON object: subsetting query details for the dataset. The object should contain the following fields:
- stringInputValues, Array<StringInputValue>, where StringInputValue is an object containing:
  - name, required, string
  - value, required, string
- stringChoiceValues, Array<StringChoiceValue>, where StringChoiceValue is an object containing:
  - name, required, string
  - value, required, string
- multiStringSelectValues, Array<MultiStringSelectValue>, where MultiStringSelectValue is an object containing:
  - name, required, string
  - values, required, Array<string>
- dateRangeSelectValues, Array<DateRangeSelectValue>, where DateRangeSelectValue is an object containing:
  - name: required, string
  - start: required, string in date-time format
  - end: required, string in date-time format
- boundingBoxValues, Array<BoundingBoxValue>, where BoundingBoxValue is an object containing:
  - name: required, string
  - bbox: required, Array<float> (4 elements)

Responses:

Code 200 (OK): a JSON object containing:
- jobId, string: ID of the subsetting job
- complete, boolean, initially false: whether the subsetting job has completed
- results, null | Array<string>, initially null: list of result URIs, or null if the job is still running. URIs will be compatible with the form /datarequest/result/{jobId}/{resultId} (see endpoint below)
Code 400 (Bad Request): returned when the user request is invalid
Code 403 (Forbidden): returned when the user has not accepted the terms & conditions for the concerned dataset
Unspecified error

GET /datarequest/status/{jobId}

Parameters:

jobId (in the URL), required, string: ID of the subsetting job

Responses:

Code 200 (OK): a JSON object containing:
- jobId, string: ID of the subsetting job
- complete, boolean: whether the subsetting job has completed
- results, null | Array<string>: list of result URIs, or null if the job is still running. URIs will be compatible with the form /datarequest/result/{jobId}/{resultId} (see endpoint below)
Code 400 (Bad Request): returned when the user request is invalid
Code 403 (Forbidden): returned when the user has not accepted the terms & conditions for the concerned dataset
Unspecified error

GET /datarequest/jobs/{jobId}/result

Parameters:

jobId (in the URL), required, string: ID of the subsetting job
size (in the URL), optional, integer: number of results to show in a page. Default: 10
page (in the URL), optional, integer: number of the page to be shown. Default: 0

Reponses:

Code 200 (OK): requested file

GET /datarequest/result/{jobId}?externalUri={externalUri}

Parameters:

jobId (in the URL), required, string: ID of the subsetting job
externalUri (in the URL), required, string: url of the product to download (link available in the response to /datarequest/jobs/{jobId}/result)

Reponses:

Code 200 (OK): requested file

GET /datarequest/jobs

Parameters:

size (in the URL), optional, integer: number of jobs to show in a page. Default: 10
page (in the URL), optional, integer: number of the page to be shown. Default: 0

Reponses:

Code 200 (OK): requested file