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

/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/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
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} This endpoint can be used to download a specific data from the result set
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 /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…

 

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.

Query Metadata sequence diagram

 

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).

Data Request sequence diagram

 

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. In this case, the Broker includes a list of URIs for the user to download the data subset.

Polling the HDA server

 

The user downloads the data using the list of external URIs (see figure below), via the /datarequest/result/{jobId}/{resultId} endpoint.

Data download

 

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 queryRequestRenderingControl 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/result/{jobId}/{resultId}

Note: the complete URI is obtained as a result of a previous GET /datarequest/status/{jobId} request.

Parameters:

  • jobId (in the URL), required, string: ID of the subsetting job
  • resultId (in the URL), required, string: ID of the individual result (part of the URI obtained from the previous GET /datarequest/status/{jobId} request)

Reponses:

  • Code 200 (OK): requested file
  • Unspecified error